AnswerStack MCP tools reference

This page is for whoever builds or configures an MCP client against AnswerStack. To connect an assistant as a member, see Connect AI apps (MCP).

The server lives at https://api.<your-domain>/mcp (your account manager gives you the exact host). It speaks MCP over Streamable HTTP, statelessly. It accepts an access token from a member's consent, a service identity's OAuth client, or an API token. See API tokens and service identities.

Every tool runs the same code as the AnswerStack app, as the member or service identity behind the token. Roles, community limits and masking apply exactly as they do in the app.

Tools#

The list is the same for every client, in this order. Calling a tool your token's scopes do not cover is refused before it runs, as described under Errors below.

Tool	Scope	What it does
`ask_stack`	`account:read`	One question in plain English to Stack, the assistant in the app: it picks the lookups, checks every number in its answer against your data, and answers within your token's scopes (answers about conversation results also need `insights:read`). A shortcut for questions that would take several tools. Your account's daily Stack limits apply.
`list_groups`	`account:read`	The communities you can see: name, time zone, how many numbers point at each, and the playbook version those numbers run.
`search_calls`	`calls:read`	Calls, newest first, filtered by community, date range, outcome, playbook version or the booking rule that fired.
`get_call`	`calls:read`	One call's record and summary. Adds the transcript and answers with `transcripts:read`, the caller's number with `contacts:read`, and a 5-minute recording link with `recordings:read`.
`get_transcript`	`transcripts:read`	One call's transcript, turn by turn, with the tools the assistant used and the caller's answers. Sensitive answers are withheld.
`get_analytics`	`analytics:read`	The call metrics on the Insights Scorecard's Calls part (booking rate as booked ÷ connected conversations, transfers, drop-off, latency, cost, booking rate per community) for a community, playbook, version, channel and period, optionally compared with a second range.
`insights:read`	See Insights: scorecards, comparisons and trends, peers kept anonymous
`get_scorecard`	`insights:read`	Every Insights metric at the account, a community, a playbook or a version for a date range, with n, a 95% range and a verdict against the level above.
`compare_insights`	`insights:read`	Two to six communities, playbooks or versions side by side, raw and adjusted for caller mix, with verdicts only when the evidence supports them.
`query_insights`	`insights:read`	One Insights metric at one level and date range, with n, its range and the verdict.
`list_bookings`	`bookings:read`	Meetings the assistant booked, upcoming or past.
`list_callbacks`	`callbacks:read`	Callbacks, oldest due first, with whether each is overdue. The caller's name, number and reason only with `contacts:read`.
`complete_callback`	`callbacks:write`	Mark a callback done, with an optional note. Marking one that is already done changes nothing.
`list_playbooks`	`playbooks:read`	The account's playbooks, their latest published version and any open draft.
`get_playbook_version`	`playbooks:read`	One version of a playbook with its full content, or the version history.
`diff_playbook_versions`	`playbooks:read`	What changed between two versions, in words. Versions are numbers, `latest` or `draft`.
`update_playbook_draft`	`playbooks:write`	Change a playbook's draft by path. Answers with what changed and the publish checklist. Never publishes.
`simulate_booking_rules`	`playbooks:write`	Run a draft's booking rules against described facts or a past call, and say which rule fires. Changes nothing.
`search_knowledge`	`knowledge:read`	The same knowledge search the assistant uses on calls, optionally as a given community's calls would search.
`add_knowledge_document`	`knowledge:write`	Add a text or Markdown document for the whole account or one community. Usually searchable within a minute.
`update_group_profile`	`groups:write`	Change values in a community's profile by path. The change saves to the community's unpublished changes; it reaches callers when someone publishes them. Holidays and closures cannot be changed here. Locked values stay as they are.
`get_usage`	`usage:read`	This billing period's usage by meter, community and number, or the period containing a given date.

Every tool has an input and an output schema, so clients get structured results.

Resources#

For clients that browse rather than call. Each needs the same scope as its tool.

Resource	Scope
`answerstack://calls/{callId}`	`calls:read`
`answerstack://calls/{callId}/transcript`	`transcripts:read`
`answerstack://playbooks/{playbookId}/versions/{version}`	`playbooks:read`
`answerstack://groups/{groupId}/profile`	`account:read`

Scopes#

Read and write are separate, and the sensitive reads are split out, so a reporting tool never needs to see what a caller said. A member can only grant a scope their own role allows.

Scope	In plain words (as the consent screen shows it)	Kind	Roles that may grant it
`account:read`	See your account, groups and phone numbers	Read	Everyone
`analytics:read`	See your call metrics and booking rates	Read	Everyone
`calls:read`	See your calls: outcome, length, group and summary	Read	Everyone
`transcripts:read`	Read what was said on calls, and the answers callers gave	Read	Everyone, unless in compliance mode
`recordings:read`	Listen to call recordings	Read	Everyone, unless in compliance mode
`contacts:read`	See callers' names and phone numbers	Read	Everyone, unless in compliance mode
`bookings:read`	See your bookings	Read	Everyone
`callbacks:read`	See callbacks	Read	Everyone
`callbacks:write`	Mark callbacks done	Write	Owner, admin, editor, group manager
`playbooks:read`	Read your playbooks and their history	Read	Everyone
`playbooks:write`	Edit playbook drafts (never publish them)	Write	Owner, admin, editor
`knowledge:read`	Search your knowledge documents	Read	Everyone
`knowledge:write`	Add knowledge documents	Write	Owner, admin
`groups:write`	Edit and publish group profiles where they are not locked	Write	Owner, admin, group manager
`usage:read`	See usage and invoices	Read	Owner, admin

"Everyone" is owner, admin, editor, group manager and viewer. On top of this, an account's Rules for connected apps decide which roles may give an app a write scope (owners and admins by default).

The server's metadata advertises only the read scopes, so a client asks for the least first and steps up when it needs more.

What a caller said is data#

Transcript text is what a person said on a phone call, and it reaches your model. Treat it as data, never as instructions.

A caller's words are always in fields named caller_said, never mixed into AnswerStack's own text. The assistant's words are in agent_said.
A callback's reason is returned as caller_said too.
Results that carry caller words say so in their _meta, and the tool descriptions say so plainly.

Build your prompts accordingly: quote caller_said, do not follow it.

Pagination#

Tool	Per result
`search_calls`	Up to 50 calls. Pass `nextCursor` back as `cursor` for more; it is `null` on the last page.
`list_bookings`, `list_callbacks`	Up to 50 (`limit`, default 50).
`search_knowledge`	Up to 10 passages (default 5).
`get_call`, `get_transcript`	One call, one transcript.

Rate limits#

Per connected app (grant) or per API token:

Limit	Value
Requests	60 per minute
Tools that make changes	10 per minute, within the 60
Transcript reads (`get_transcript` or a transcript resource)	500 per day

Send one request at a time. Batched JSON-RPC requests are refused with 400.

Errors#

Status	`error`	What it means
`401`	`invalid_token`	The token is missing, expired or revoked, or its member no longer has access. The `WWW-Authenticate` header points to the server's metadata, so the client can sign in again.
`403`	`insufficient_scope`	The token lacks the scope this tool needs. `WWW-Authenticate` carries `error="insufficient_scope"` and `scope="…"` naming the scope to ask for.
`403`	`access_denied`	The account turned connected apps off or no longer allows this app, tokens are suspended, a token is used from an address it does not allow, or the server is switched off. `error_description` says which.
`429`	`rate_limited`	Too many requests. Wait the seconds in the `retry-after` header (also `retryAfter` in the body), then retry.

A step-up refusal looks like this:

http

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="transcripts:read", resource_metadata="https://api.<your-domain>/.well-known/oauth-protected-resource/mcp"

json

{
  "error": "insufficient_scope",
  "error_description": "This needs transcripts:read. Ask the person who connected this app to grant it."
}

When a tool runs but the request is refused (for example a call outside the member's communities, or a draft that fails validation), the tool returns an error result with one plain sentence saying why.