# Puzzle over MCP

Puzzle is an accounting platform for startups. It pulls in bank, card, payroll and payment
activity, categorizes it, and keeps double-entry books. These tools read and manage one
company's books at a time.

## Companies

- A connection covers one or more companies, or every company the user can access.
- Every tool takes `companyId`. It is optional only when the connection covers exactly one
  company. Call `list_companies` for the ids.
- A company outside the connection is refused. The user adds companies in Puzzle under
  Settings → Connected apps.

## Read-only and write access

- New connections are read-only: only tools that don't change the books are listed.
- Calling a write tool on a read-only connection returns an error naming the tool.
- Write access is per connection. `request_write_access` returns the disclaimer
  (`puzzle://docs/write-access`); show it to the user verbatim, and call it again with
  `acknowledgedDisclaimer: true` only after an explicit yes. Then list tools again.
- The user can also change it in Puzzle under Settings → Connected apps.
- With write access, confirm each change with the user before making it.
  `disable_write_access` sets the connection back to read-only.

## Plans

Companies without a paid Puzzle plan get every tool for a grace period, then a limited
read-only toolset with no write access. A gated tool is refused with the company's plan status.
`list_companies` shows each company's plan, and `puzzle://docs/plan` explains the tiers.
The refusal includes the billing link, and `upgrade_puzzle` returns it.

## Rate limits

Each tool has a per-minute and a per-day limit, and each connection has an overall per-minute
limit. A tool's limits are per company and scale with the company's Puzzle plan. Daily counts
reset at 00:00 UTC. A result notes when a tool is close to its daily limit, and the server
instructions list the tools that have already reached it. Over a limit, the tool returns an error
with `retryAfterSeconds`. Reference data (chart of accounts, accounts, classes) doesn't change
within a session: fetch it once and reuse it.

## Skills

Skills are Puzzle's playbooks for multi-step work (closing a month, bills, reconciliation).
Call `list_skills` for a company's skills and `get_skill` for one before starting. They are also
resources (`puzzle://companies/{companyId}/skills/{skillId}`) and prompts.

## Payroll management

Use `listPayrolls` to find a run and `getPayroll` to inspect its workers, compensation lines,
account mappings, reporting classes and related bank transactions. With write access, confirm
the intended change before using `postPayroll`, `resyncPayrollFromSource`,
`updatePayrollCompensations` or `deletePayroll` (which requires a reason).
Some mapping edits depend on the company's payroll setup: check `getPayroll`'s
`canMapCompensationAccounts`, `canAssignClasses`, `canMapCompensationBenefits` and
`canMapEmployeeBenefitLiabilities` flags before proposing those changes.

Posting records payroll in the ledger; it does not pay workers. Resync refreshes an existing
run from its connected provider, including Gusto; check `canResyncFromSource` first. Mapping
and class edits apply to the selected run, not future-run defaults. Re-read `getPayroll` after
an edit to verify it: `benefitAccountMappings` reports the selected run's mappings, while
`mappedCompanyBenefits` contains company defaults. Line edits support expense accounts only;
apply classes and benefit expense mappings to whole compensations. Linked bank activity is
available in `relatedTransactions` even when the run has no journal event.
If posting returns `success: false`, report its validation errors. A successful response means
the payroll was accepted and its accounting events queued; wait for a later `getPayroll` to
report `status: posted` before saying posting has completed.
Deleting removes the accounting record in Puzzle; it does not cancel provider payments.