Skip to main content
The server exposes 27 curated tools, not one tool per API endpoint. Names are in English, like the API.

​
Your key decides what the assistant sees

  • tools/list only returns the tools the key’s scopes allow. With a read-only key the assistant does not even know create_call exists.
  • Every tools/call checks the scope again. A client that calls a tool it was not shown gets an insufficient_scope error, not the result.
To change what an assistant can do, change the key: create a new one with other scopes in Settings > API keys and swap it in your client’s configuration. Scopes are explained in Authentication.

​
Tool catalog

Read tools carry the MCP readOnlyHint annotation. The three tools that act on real calls carry destructiveHint and openWorldHint, so clients that honor annotations can ask you before running them; update_agent, publish_agent and assign_phone_number carry destructiveHint too, because they change what live calls use. How the confirmation of the three works is in Security and spending.

​
Ask for summaries, not pages

The tools are built so an assistant gets its answer in few calls:
  • List tools return 50 items by default, up to 100 per call, accept the filters in the table and return a next_cursor for the next page.
  • Lists leave out heavy fields: list_calls does not include transcripts. Ask for one call with get_call when you need what was said.
  • get_call_stats answers aggregate questions (“how many calls failed yesterday?”, “which agent spent the most this week?”) in one call, instead of paging through hundreds of calls. It counts up to 1,000 calls per range; if there were more, it says so with truncated: true and the real total in calls_in_range, so the assistant can narrow the range.

​
Rate limits

The MCP has no separate limit: it draws from your account’s bucket, the same one the API uses.
  • Every tool call counts as one request against your plan’s per-minute limit, once, never more.
  • initialize, tools/list and the rest of the protocol do not count.
  • For the three tools that ask for confirmation, only the call that runs counts. The confirmation step does not.
  • The per-IP check of the API applies to every request, including initialize and tools/list.
The numbers per plan and how the bucket refills are in Rate limits. An assistant that pages through calls one by one burns the bucket quickly; one that asks get_call_stats does not.

​
Errors

When a tool fails, the server does not break the MCP session: it returns a normal tool result with isError: true and the same envelope as the API, both as structuredContent and as text:
The assistant can read error and decide what to do: wait after rate_limit_exceeded, tell you the key needs another scope after insufficient_scope, fix an argument after invalid_body, get a new token after invalid_confirmation, or stop after key_budget_exhausted. The full list of codes is in Errors. If you report a problem, send us the request_id. A successful result carries its JSON the same way: in structuredContent and as text. A missing, invalid or revoked key never reaches the tools: the HTTP request itself is refused with 401.