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.

The confirm contract: the server asks, the person decides, the caller carries the answer.
The first call
{
  "name": "instructions_publish",
  "arguments": {
    "instructionId": "acme/support-agent",
    "message": "Refunds over €150 need a person."
  }
}
It asks first
{
  "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
}
The person agreed: the same call, with the token
{
  "name": "instructions_publish",
  "arguments": {
    "instructionId": "acme/support-agent",
    "message": "Refunds over €150 need a person.",
    "confirmToken": "eyJ0IjoiaW5zdHJ1Y3Rpb25zX3B1Ymxpc2gi…"
  }
}
The answer
{
  "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 confirmToken and idempotencyKey. Change any argument, or write the same instruction another way (acme/support-agent instead of its ins_… 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.

Shell
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.

A create a retry can't repeat
{
  "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:
The key was used for another call
{
  "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_create sent again answers the agent without its secret; rotate it with orgs_agents_rotate for 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.

An edit on revision 14
{
  "name": "instructions_draft_edit",
  "arguments": {
    "instructionId": "acme/support-agent",
    "expectedRevision": 14,
    "ops": [{ "op": "replace", "find": "over €200", "text": "over €150" }]
  }
}
Someone changed the draft meanwhile
{
  "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.

Read the draft again
{
  "name": "instructions_get",
  "arguments": { "instructionId": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V", "include": ["draft"] }
}
The edit, made on revision 15
{
  "name": "instructions_draft_edit",
  "arguments": {
    "instructionId": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V",
    "expectedRevision": 15,
    "ops": [{ "op": "replace", "find": "over €200", "text": "over €150" }]
  }
}
The answer
{
  "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.

Set the visibility it has
{
  "name": "instructions_visibility_set",
  "arguments": { "instructionId": "acme/support-agent", "visibility": "internal" }
}
The answer
{
  "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.

The first page
{
  "name": "instructions_list",
  "arguments": { "owner": "acme", "limit": 50 }
}
Its answer
{
  "items": [ … 50 instructions … ],
  "nextCursor": "eyJvIjo1MH0"
}
The next page
{
  "name": "instructions_list",
  "arguments": { "owner": "acme", "limit": 50, "cursor": "eyJvIjo1MH0" }
}
The last page
{
  "items": [ … 12 instructions … ],
  "nextCursor": null
}
  • Send nextCursor back as cursor, with the same other arguments. null, or no nextCursor, 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_list pages by its place in the history instead, so new events don't shift it.
  • A limit outside 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 required names only what every success has, including a changed: false answer and an answer given again.
  • An error answer has error instead, 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:

HintTrue whenTools
readOnlyHinteffect is read: nothing another person or agent could see changes73
destructiveHinteffect is destructive: it deletes or overwrites what can't be restored, changes what others receive or may access, or raises what can be spent61
idempotentHinta read, or a tool whose repeat with the same arguments has no further effect156
openWorldHintit 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/alwaysLoad on session_bootstrap, capabilities_search, instructions_list, instructions_get, instructions_draft_edit: Claude Code loads these at the start rather than behind its tool search.
  • anthropic/requiresUserInteraction on the tools that can't be undone, above.
  • openai/toolInvocation/invoking and invoked on the most used tools: what ChatGPT shows while the tool runs and after.
  • md.instruction/class and md.instruction/toolset on 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.

Last checked against the product:

Was this page helpful? Report a problem