# 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. 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.