Contracts: confirm, idempotency, revisions, paging
This page is for developers who call the MCP server's tools from a host, an agent or their own code. It describes the rules every tool follows: asking before a change others feel, making a retry safe, refusing an edit made on a stale read, and paging a list.
How an answer looks
Every tool answers an MCP tool result. Its structuredContent is the answer as JSON, and its first content block is the same JSON as text. Addresses the answer names in links come as resource_link blocks too, so a host can offer to read them.
An error is a tool result with isError: true, not a JSON-RPC error. Its structuredContent is {"error": {"code", "message", "details"}}. details.field names the argument at fault, and details.next says what to do next. Every code is on Errors.
Needs confirmation
A tool that changes what other people or agents receive, or that can't be undone, asks first. Called without confirmToken, it changes nothing and answers the error needs_confirmation. The person decides; the caller only carries the answer.
{
"name": "instructions_publish",
"arguments": {
"instructionId": "acme/support-agent",
"message": "Refunds over €150 need a person."
}
} {
"content": [{ "type": "text", "text": "{\"error\": {…}}" }],
"structuredContent": {
"error": {
"code": "needs_confirmation",
"message": "Release v8 of Support agent as latest?",
"details": {
"summary": "Release v8 of Support agent as latest?",
"consequences": [
"3 agent(s) following latest switch to v8.",
"1 pending suggestion(s) are left out of it."
],
"confirmToken": "eyJ0IjoiaW5zdHJ1Y3Rpb25zX3B1Ymxpc2gi…",
"expiresIn": 600,
"next": "Show the person the summary and the consequences, and ask them. Only if they agree, call instructions_publish again with the same arguments plus this confirmToken: it works for 10 minutes, for this call by you alone (sent again, the call answers what it did). If they don't agree, do nothing more: nothing has changed."
}
}
},
"isError": true
} {
"name": "instructions_publish",
"arguments": {
"instructionId": "acme/support-agent",
"message": "Refunds over €150 need a person.",
"confirmToken": "eyJ0IjoiaW5zdHJ1Y3Rpb25zX3B1Ymxpc2gi…"
}
} {
"version": { "id": "ver_…", "number": 8, "signed": true, "refs": ["latest"], … },
"instruction": { "id": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V", "owner": "acme", "name": "support-agent", … }
} | Field | What it is |
|---|---|
summary |
One line saying what the call would do, to show the person as it is |
consequences |
What follows from it, one line each: who switches, who can read it, what is left out |
confirmToken |
The token to send back, once, with the same arguments |
expiresIn |
Seconds the token works: 600 |
next |
The step for a model, naming the tool to call again |
What the token is bound to
- The caller. Only the person or agent the token was given to can use it.
- The tool and the arguments. The token works only for the same tool with the same arguments, apart from
confirmTokenandidempotencyKey. Change any argument, or write the same instruction another way (acme/support-agentinstead of itsins_…id), and the token is refused. - Once. A token used once is spent.
- 10 minutes. After that it is refused as expired. Call again without it for a new summary, and ask the person again.
Sending the confirmed call again is safe. If its answer was lost on the way, the same call with the same token answers what the first one did and does nothing more. A secret the first answer showed once, such as an agent's client secret, is not repeated: rotate it for a new one.
A refused token answers validation with details.reason:
reason |
Why | What to do |
|---|---|---|
invalid |
It isn't a token this server gave | Call without confirmToken and use the token it answers |
expired |
More than 10 minutes passed | Call without it, and ask the person again |
mismatch |
Another tool, caller or set of arguments | Call without it to ask about this call |
used |
It was used already, for an answer that wasn't kept | Call without it, and ask the person again |
Never confirm for the person
A caller shows the summary and the consequences to the person and sends the token only if they agree. A model must not confirm on its own judgement, and a host must not send the token automatically. The CLI does the same: instruction publish, instruction revoke and instruction refs … set show what the server said and ask. Without a terminal, --yes is the person's agreement given in advance; without it they change nothing and exit with code 7.
instruction publish acme/support-agent --message "Refunds over €150 need a person."
# shows the summary and the consequences, and asks; without a terminal:
instruction publish acme/support-agent --message "Refunds over €150 need a person." --yes Some tools ask only sometimes. instructions_publish asks when it moves the default ref, on the first release, or when it makes the instruction public; a quiet version (refs: []) is released without asking. The first release also needs visibility (private, internal or public): without it, the call answers validation asking who can read the first version, before it asks to confirm. A draft with nothing new since the latest version answers conflict, "nothing changed since the latest version", and asks nothing. A call that would change nothing (changed: false, below) asks nothing either.
The tools that ask
These 39 tools can answer needs_confirmation:
instructions_draft_discard, instructions_delete, instructions_purge, folders_delete, projects_delete, instructions_proposals_merge, instructions_publish, instructions_refs_set, instructions_refs_delete, instructions_schedules_create, instructions_versions_revoke, instructions_visibility_set, instructions_access_set, instructions_transfer, deployments_rules_delete, orgs_delete, orgs_members_remove, orgs_workspaces_delete, orgs_signin_provider_save, orgs_signin_provider_remove, orgs_signin_domains_remove, orgs_signin_set, orgs_keys_retire, orgs_keys_revoke, seal_workspaces_enable, seal_workspaces_rotate, instructions_sealed_publish, orgs_agents_rotate, orgs_agents_revoke, orgs_apps_update, orgs_apps_rotate, orgs_apps_revoke, orgs_domains_remove, orgs_apps_policy_set, admin_staff_set, admin_apps_review, me_apps_revoke, me_delete, support_requests_recover
Of these, instructions_purge, instructions_versions_revoke, orgs_delete, orgs_keys_revoke, orgs_agents_rotate, orgs_agents_revoke, me_delete can't be undone. They also carry anthropic/requiresUserInteraction, so Claude Code asks the person before each call, even in its automatic modes, and the server's confirmation asks again.
Idempotency keys
A tool that creates something takes idempotencyKey: any unique string you choose. Send the same call again with the same key, and it answers what the first call made instead of making a second one.
{
"name": "instructions_create",
"arguments": {
"workspaceId": "ws_…",
"name": "refund-rules",
"content": "---\nspec: \"1\"\n---\n# Refund rules\n…",
"idempotencyKey": "ci-run-4182-refund-rules"
}
} - The answer is kept for 24 hours, for this caller.
- The key is bound to the tool and the arguments. The same key on a different call answers
conflict:
{
"error": {
"code": "conflict",
"message": "this idempotency key was used for a different call",
"details": { "idempotencyKey": "ci-run-4182-refund-rules" }
}
} - Two calls with the same key at the same moment don't both run: the second waits for the first and answers what it did.
- A secret shown once is not kept with the answer.
orgs_agents_createsent again answers the agent without its secret; rotate it withorgs_agents_rotatefor a new one.
Use a key that names the work, such as a CI run and a file, so a retried job finds its own answer. The tools that take one:
instructions_create, instructions_duplicate, folders_create, projects_create, instructions_suggestions_create, instructions_comments_create, instructions_comments_reply, instructions_proposals_create, instructions_schedules_create, instructions_export, instructions_access_requests_create, instructions_fork, instructions_links_create, instructions_bindings_create, deployments_rules_create, deployments_create, deployments_asks_create, deployments_messages_send, orgs_create, orgs_invitations_create, orgs_workspaces_create, orgs_integrations_add, orgs_integrations_apis_add, orgs_people_directories_add, orgs_scim_tokens_create, orgs_keys_add, orgs_keys_rotate, seal_keys_register, seal_unlocks_add, seal_wraps_add, seal_workspaces_rotate, orgs_agents_create, orgs_apps_create, orgs_apps_rotate, orgs_domains_add, me_export, instructions_audit_export, orgs_billing_checkout
Expected revisions
A tool that changes a draft, or something many people edit, takes expectedRevision: the revision you read. If it changed since, the call changes nothing and answers version_conflict, with the revision now and the call to read it again.
{
"name": "instructions_draft_edit",
"arguments": {
"instructionId": "acme/support-agent",
"expectedRevision": 14,
"ops": [{ "op": "replace", "find": "over €200", "text": "over €150" }]
}
} {
"error": {
"code": "version_conflict",
"message": "the draft changed since you read it: it is at revision 15 now",
"details": {
"currentRevision": 15,
"reread": { "tool": "instructions_get", "arguments": { "instructionId": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V", "include": ["draft"] } },
"next": "Read it again (instructions_get {\"include\": [\"draft\"], \"instructionId\": \"ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V\"}), make your change on what you read, and send it with expectedRevision 15."
}
}
} Read again with the call in details.reread, make the change on what you read, and send it with the new revision. Don't send the same change again with only the revision changed: the text it was meant for may have moved.
{
"name": "instructions_get",
"arguments": { "instructionId": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V", "include": ["draft"] }
} {
"name": "instructions_draft_edit",
"arguments": {
"instructionId": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V",
"expectedRevision": 15,
"ops": [{ "op": "replace", "find": "over €200", "text": "over €150" }]
}
} {
"revision": 16,
"pendingSuggestions": 0,
"openThreads": 1,
"suggestions": [],
"links": ["instruction://ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V/draft"]
} The draft's revision is draft.revision in instructions_get (or its resource, instruction://{id}/draft). Each successful edit answers the next revision, so a sequence of edits needs no read between them.
instructions_draft_edit sent again on the revision it already moved past answers what it did the first time, for an hour, instead of version_conflict. A release sent again on the same draft revision answers the version it made. Anyone else's call on that revision still gets the conflict. instructions_draft_edit requires expectedRevision; on the other tools it is optional, and without it the call doesn't check. The tools that take it:
instructions_draft_replace, instructions_draft_edit, instructions_restore, instructions_update, instructions_suggestions_create, instructions_suggestions_accept, instructions_suggestions_reject, instructions_proposals_update, instructions_publish, instructions_visibility_set, instructions_access_set, instructions_sealed_draft_put, me_preferences_set
Nothing to change
A call that asks for what already holds writes nothing and answers changed: false with a reason. It asks no confirmation either.
{
"name": "instructions_visibility_set",
"arguments": { "instructionId": "acme/support-agent", "visibility": "internal" }
} {
"instruction": { "id": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V", "visibility": "internal", … },
"changed": false,
"reason": "it is internal already"
} So a retry of a change that went through is safe, and a script can set a state without reading it first. Revoking an agent credential or a read link that is revoked already answers the same way.
Paging
26 tools answer a list one page at a time. Most take limit with a default of 50 and a maximum of 200; each tool's own figures are in Rate and size limits.
{
"name": "instructions_list",
"arguments": { "owner": "acme", "limit": 50 }
} {
"items": [ … 50 instructions … ],
"nextCursor": "eyJvIjo1MH0"
} {
"name": "instructions_list",
"arguments": { "owner": "acme", "limit": 50, "cursor": "eyJvIjo1MH0" }
} {
"items": [ … 12 instructions … ],
"nextCursor": null
} - Send
nextCursorback ascursor, with the same other arguments.null, or nonextCursor, means the last page. - Treat a cursor as opaque, and send only one the server gave. One it can't read answers
validation, "invalid cursor". - Lists page by position. An item added or removed between two calls can shift where the next page starts.
instructions_activity_listpages by its place in the history instead, so new events don't shift it. - A
limitoutside 1 to the maximum is brought inside it.
The server's own MCP lists (tools/list, resources/list, prompts/list) are paged by MCP's own nextCursor. Follow it until it is absent, so you don't miss tools on a later page.
detail: full
A few lists answer each item as a summary by default: what a caller acts on, such as id, name, title, role and the latest version. detail: "full" asks for each item whole. The tools that take it: instructions_list, instructions_search, instructions_versions_list, orgs_members_list, instructions_activity_list, instructions_audit_query.
Large answers
instructions_get with include: ["draft"] returns the draft's text up to 100,000 characters. A longer draft comes as draft.textUri, its instruction://{id}/draft address, with draft.textOmitted saying why; read the resource for the text. A draft holds at most 1,000,000 characters.
The tools whose answer can be a long text tell Claude Code to keep it in the conversation rather than in a file, up to a size: instructions_get (150,000 characters), instructions_proposals_get (150,000 characters), instructions_versions_read (150,000 characters), instructions_diff (150,000 characters), instructions_export (150,000 characters). Other size limits are in Rate and size limits.
Output schemas
103 of the 221 tools publish an outputSchema: what a successful answer's structuredContent holds. The gateway checks each successful answer against it and fails one that doesn't match, so a client can rely on the fields the schema names.
- A schema's
requirednames only what every success has, including achanged: falseanswer and an answer given again. - An error answer has
errorinstead, and still passes the schema. - More fields than the schema names may come. Don't refuse an answer for an unknown field.
The input schemas are closed: an argument the tool doesn't read is refused, naming it, rather than ignored.
Tool hints
Every tool carries all four MCP hints, worked out from what it does, never from who may call it:
| Hint | True when | Tools |
|---|---|---|
readOnlyHint | effect is read: nothing another person or agent could see changes | 73 |
destructiveHint | effect is destructive: it deletes or overwrites what can't be restored, changes what others receive or may access, or raises what can be spent | 61 |
idempotentHint | a read, or a tool whose repeat with the same arguments has no further effect | 156 |
openWorldHint | it reaches a third party (Stripe) | 12 |
Every tool that asks to confirm is destructive. The hints help a host decide when to ask its user. They grant nothing: the server checks the caller's scopes and role on every call, whatever the hints say.
The server adds a few hints of its own for particular hosts:
anthropic/alwaysLoadonsession_bootstrap,capabilities_search,instructions_list,instructions_get,instructions_draft_edit: Claude Code loads these at the start rather than behind its tool search.anthropic/requiresUserInteractionon the tools that can't be undone, above.openai/toolInvocation/invokingandinvokedon the most used tools: what ChatGPT shows while the tool runs and after.md.instruction/classandmd.instruction/toolseton every tool: its permission class and its group.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
needs_confirmation |
The call changes what others receive, or can't be undone | Show summary and consequences to the person; send confirmToken only if they agree |
validation, details.reason: "mismatch" |
The arguments differ from the first call | Send exactly the first call's arguments, plus the token |
validation, details.reason: "expired" |
More than 10 minutes passed | Call without the token, and ask the person again |
version_conflict |
Someone changed it since you read it | Read again with details.reread, and redo the change on what you read |
conflict, "this idempotency key was used for a different call" |
One key on two different calls | Use a new key for each distinct call |
validation, "invalid cursor" |
A cursor from another list or made by hand | Start from the first page |
| Still stuck | Send a request |
Generated from the code
The tool lists and counts on this page are read from the tool registry (packages/registry/registry.json), and the host hints from the gateway's generated configuration (deploy/mcpg/prod.yaml), when the docs are built.