Skip to content
IsoKron

Write-surface design for MCP tools

A safe MCP write tool takes an idempotency key on creates, an expected version on updates and deletes, a dry-run or confirm argument on deletes, and changes only the fields named; annotations cannot provide any of this.

Models retry when an answer is lost and act on data that may be stale. Without a retry key a repeated create makes a duplicate; without a version check an update silently overwrites someone else’s change. A tool list shows whether the tools offer these arguments, which is what these checks read.

Whether the server honours them only a test against a running server can show. The MCP Write-Safety Requirements define those tests.

The 10 checks

  • Write tools say whether a retry repeats the effect: OpenAI asks that tools be safe to retry where possible, or say when a retry repeats the effect; mark naturally repeatable writes with idempotentHint: true, and say so in the description of writes that are not.
  • Create and send tools take a retry key: A create or send tool should accept an idempotency key from the caller, so a retry after a lost answer returns the first result instead of creating a duplicate (MWS-RETRY-1).
  • Update and delete tools take a version or precondition: Update and delete tools should take an expected version (an ETag, revision or updated_at) and refuse the write with a conflict when the object changed since it was read; otherwise a stale write silently replaces another writer’s change (MWS-CONC-2).
  • Delete tools take a confirm or dry-run argument: Give delete tools a dry_run (default true) or confirm argument, so the model can show what will be removed before the irreversible call; OpenAI notes annotations do not replace human confirmation for irreversible operations.
  • Updates send the change, not the whole object: An update tool that replaces the whole object overwrites every field the caller sends, including ones it did not mean to change; offer a field patch (only the named fields change) or an update_mask, and require a version on full replacement.
  • Bulk deletes have a guard: A delete tool that takes many targets must not treat an empty, missing or match-all selector as "everything" unless the caller opts in explicitly, and should offer a dry run and cap the batch size (MWS-TGT-2).
  • Reads and writes are separate tools: A single tool that accepts both safe methods (GET, HEAD, OPTIONS) and unsafe ones (POST, PUT, PATCH, DELETE) is rejected by the Anthropic directory, because no hint can be true for it; split it into a read tool and write tools.
  • Deleting tools are not marked non-destructive: Tools that delete, overwrite, cancel, revoke or reset must set destructiveHint: true; with false, clients run them without a confirmation prompt, and both directories treat that as incorrect annotations.
  • Unknown arguments are rejected: Set "additionalProperties": false at the root of inputSchema and reject unknown arguments on the server, so a misspelled argument fails loudly instead of being silently dropped.
  • Tools that create state say how long it lasts: A tool that creates a session, cart, context or other handle should say in its description how long the handle lasts, because handles outlive any single connection and the model decides whether to create one.

Other topics

Sources last verified on 2026-11-18. How findings become grades.

Check your tool list: paste your tools/list, nothing is sent anywhere