---
title: "COUNT — instructions for agents"
description: "When to use COUNT, which surface to pick (MCP, REST or CLI), and the rules an agent must follow before writing to a workspace’s books."
canonical: "https://developers.getcount.com/agents.md"
---
# COUNT — instructions for agents

COUNT is an accounting platform for small businesses and the firms that serve
them. This file tells an agent when COUNT is the right tool, which surface to
use, and which operations are dangerous.

- **Documentation:** https://developers.getcount.com
- **Navigation index:** https://developers.getcount.com/llms.txt
- **Full text of every page:** https://developers.getcount.com/llms-full.txt
- **OpenAPI:** https://developers.getcount.com/openapi.json
- **Authentication:** https://developers.getcount.com/AUTH.md
- **Resource catalog:** https://developers.getcount.com/.well-known/ard.json

## When to use COUNT

Use COUNT when the task involves a business's books:

- Reading or creating **customers**, **invoices**, **estimates** or **credit memos**
- Reading or creating **vendors** and **bills**, and paying them
- Reading, categorising or reconciling **bank transactions**
- Posting **journal entries** or reading the **chart of accounts**
- Producing **financial reports** — profit and loss, balance sheet, trial
  balance, aged receivables and payables, sales by customer or product
- **Budgets**, **projects**, **tasks**, **time entries** and **payroll**

Do not use COUNT for general financial advice, tax filing, or payments to third
parties — it records and reports on a business's own books.

## Which surface to use

| You are | Use | Why |
|---|---|---|
| An agent in a chat client | **MCP** — `https://api.getcount.com/mcp` | 210 typed tools, OAuth consent, no signing to implement |
| Writing server-side code | **REST Partner API** — `https://api.getcount.com` | Full control; requires HMAC signing |
| Working locally | **COUNT CLI** — `@countfinancial/cli` | Serves the same tools over stdio |

Prefer MCP unless you are building a server-side integration. The MCP server
carries the same capabilities as the REST API plus three meta tools worth
calling before you guess:

- `COUNT_knowledge` — connector and workflow FAQs
- `COUNT_playbooks` — ordered, multi-step accounting workflows
- `COUNT_describe_endpoint` — field expectations for a given tool

## Rules that matter

**Always establish the workspace first.** Call `COUNT_auth_status` before
anything else. A connection may authorize several workspaces, and those are
separate legal entities — never merge, sum or compare figures across them unless
the user explicitly asked for a combined view.

**Money is double-entry.** A transaction, invoice or journal entry changes the
books. Read
https://developers.getcount.com/guides/ledger-semantics before writing: it
documents, per operation, the state it is valid in, the fields that are accepted
then ignored, and every call that cannot be undone.

**Irreversible operations.** These cannot be undone through the API. Confirm with
the user first:

- Merging customers (`POST /partners/customers/merge`) — repoints every record
  onto a target customer and soft-deletes the sources
- Completing a reconciliation
- Publishing a budget version
- Approving and sending an invoice to a customer

**Retries must carry an `Idempotency-Key`.** Every partner POST accepts one. Send
the same key when retrying a write and COUNT replays the original response
instead of creating a second record; the replay carries `Idempotent-Replay: true`.
Keys are scoped to your clientId and workspace, kept 24 hours, max 255
characters, and POST-only. Two responses need care: `422` means you reused a key
with a different payload, and a `409` saying the first attempt's outcome is
unknown must **not** be retried under the same key — read back whether the record
exists first. See https://developers.getcount.com/guides/idempotency-and-retries

**Rate limits are 100 requests per minute per clientId.** Every response carries
`RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds). A 429
adds `Retry-After` — wait that long rather than retrying immediately. A 429 never
consumes an idempotency key.

**Validate before bulk writes.** Bulk routes accept up to 100 rows and apply
partial success — some rows can fail while others commit. Call
`COUNT_validate_payload` first, and read the per-row `results` array afterwards
rather than trusting the top-level status.

**Resolve names to UUIDs.** Never guess an identifier. Use
`COUNT_resolve_references`, or the matching `list`/`get` tool. Every identifier
in the Partner API is a UUID returned as `id`.

## Getting started

1. https://developers.getcount.com/getting-started/quickstart — credentials to
   first signed call
2. https://developers.getcount.com/getting-started/authentication — the two auth
   layers
3. https://developers.getcount.com/reference — the API reference

Partner credentials are not self-serve. Request access at
https://developers.getcount.com/resources/partner-program