> ## Documentation Index
> Fetch the complete documentation index at: https://developers.sapot.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool Reference
> The 46-tool MCP catalog grouped by capability scope, with shared return conventions and links to every per-domain page.
Staging-verified; production rolling out. Tool names and arguments are stable — treat the MCP server URL as environment-specific until GA.
The Sapot Chat MCP server exposes **46 tools across 7 domains**. Every tool is backed by a live REST endpoint and is unlocked by a **capability scope** carried on your agent key. A tool whose scope your key wasn't granted is simply invisible to that key — this is default-deny by design, not an error.
This section is the technical reference. Each domain has its own page listing every tool with its **scope**, **arguments**, and **return shape**.
## Tools by scope
| Scope | Tools | Count |
| --------------------- | -------------------------------------------------------------- | ------ |
| `conversations:read` | list / count / search / filter / get + read messages | 6 |
| `conversations:write` | reply, assign, set status, set priority, label | 5 |
| `contacts:manage` | list / search / filter / create / update / label + list labels | 7 |
| `reports:read` | summary, timeseries, counts, entity summary, live | 5 |
| `knowledge:manage` | entries CRUD + search + approve + profile get/update | 8 |
| `templates:manage` | list / create / update / delete / sync WhatsApp templates | 5 |
| `flows:manage` | list / get / metrics / set inboxes | 4 |
| `flows:publish` | publish a flow agent | 1 |
| `campaigns:draft` | list / get / preview audience / draft / update draft | 5 |
| **Total** | | **46** |
Scopes are additive and independent. A key with only `conversations:read` can read the inbox but cannot reply; a key with `flows:manage` but not `flows:publish` can attach inboxes but cannot take an agent live.
## How to read a domain page
Every tool entry on the per-domain pages follows the same layout:
The exact capability scope the key must carry. If it's missing, the call returns `Access token is missing the required scope: `.
A table of argument names, types, and behavior — matched verbatim to the tool signature. Defaults are noted; the **account id is never an argument** (it's fixed by the `X-Sapot-Account-Id` connection header).
The response shape the tool hands back, using the envelope conventions below.
## Return-envelope conventions
The tools proxy Sapot Chat's REST API, so responses follow its shapes. Three patterns cover almost everything:
| Pattern | Shape | Used by |
| ------------- | -------------------------------------------------------- | --------------------------------------- |
| List + counts | `{meta: {…counts / pagination}, payload: [ … ]}` | most read/search/filter tools |
| Nested data | `{data: {meta, payload}}` or `{data: [ … ], meta}` | conversation listing; knowledge listing |
| Single object | the created/updated resource (sometimes under `payload`) | create/update/get tools |
Notes that trip people up:
* **`payload` is the array of records; `meta` holds the counts and pagination.** Read `meta` before assuming there's a next page.
* Some success responses are **empty** — deletes, `set_conversation_priority`, and an "unassign" all return `{}`. That's success, not a silent failure.
* `search_knowledge` is the odd one out: it returns `{text_context, entries: […]}` — the same retrieval the AI runtime uses.
### Page sizes
Pagination is per-domain and fixed server-side:
| Domain | Page size |
| ------------------------------------------ | ------------------------------------------------------------ |
| Conversations (list/search/filter) | 25 per page |
| Contacts (list) | 15 per page |
| Knowledge entries (list) | 25 per page |
| Reports, flow agents, campaigns, templates | not paginated (full list, or Meta-side paging for templates) |
Paginated tools take a 1-based `page` argument; increment it and re-call to walk the pages.
## Metering
Only **allowed, successful (2xx)** calls count against your plan's per-billing-period action quota. A denied (`401`/`403`), not-found, or invalid (`422`) call consumes nothing. When the quota is exhausted, tools return `429` with `Agent action quota exceeded for the current billing period`; it resets at the next billing-period renewal.
## Boundaries shape two domains
Two domains are deliberately narrowed to honor the locked product boundaries — read [Safety & Boundaries](/ai-agents/safety-boundaries) before relying on them:
* **Flow agents are intent-level only.** You list, inspect, attach inboxes, and publish — but the Designer graph (`graph_data` / `graph_snapshots` / `designer_history`) is stripped server-side, and there is no build-from-scratch, export, or import tool.
* **Campaigns are draft-only.** A campaign created or edited via an agent key is forced into a non-sending `draft` state. An agent prepares the blast; a human sends it from the dashboard.
## The domains
Read, search, and filter conversations; reply, assign, resolve, prioritise, and label. (11 tools)
Find, create, update, and label contacts; resolve numeric label ids. (7 tools)
KPI summaries, single-metric time series, leaderboards, and live counts. (5 tools)
Curate FAQs, products, and promos, plus the always-on business profile. (8 tools)
List, create, update, delete, and sync Meta message templates. (5 tools)
Operate and publish flow agents at the intent level. (5 tools)
Preview audiences and prepare campaign drafts for a human to send. (5 tools)
Not connected yet? Start with the Quickstart at /ai-agents/quickstart, or read the scope model at /ai-agents/authentication.