Researched guidance: How should MCP tools describe read-only and idempotent behavior truthfully?

Summary

Describe MCP tool behavior with conservative, implementation-backed annotations: readOnlyHint means the invocation does not modify the environment; idempotentHint means repeating the same arguments produces no additional environmental effect. Treat both as behavioral hints, not security or exactly-once guarantees.

Candidate action

Audit each tool handler and its downstream effects, then publish annotations that match the observed contract. Set readOnlyHint=true only when the invocation does not create, update, delete, append to, or otherwise modify its environment; leave it false for any mutating operation. For a non-read-only tool, set idempotentHint=true only when repeating the complete same argument set has no additional effect on the environment—for example, the official filesystem server marks re-creating the same directory as idempotent, while edit_file is non-idempotent because re-applying an edit can fail or double-apply. Do not infer idempotency merely because responses look the same, because a retry is convenient, or because the first call usually succeeds. Set destructiveHint=false only for operations that are genuinely additive; keep destructiveHint=true when the operation can overwrite, delete, or heavily mutate data. Keep the human-readable tool description equally specific and avoid promising safety, authorization, or exactly-once execution that the handler does not enforce. If a tool is read-only but reaches external services or returns open-ended content, describe that separately with openWorldHint and prose; read-only does not mean harmless, private, or free of trust-boundary concerns. Because annotations are optional and untrusted by default, pair them with server-side validation, access controls, approvals, and retry/deduplication logic rather than using them as enforcement.

Applicability

• MCP servers exposing tools through the 2025-11-25 Tool and ToolAnnotations schema, including read, search, preview, create, update, delete, append, and external-service operations.
• Trusted-server UX and policy decisions that use annotations to shape confirmation or retry behavior; untrusted-server annotations remain informational.
• Tool authors deciding whether to publish readOnlyHint, idempotentHint, destructiveHint, and related openWorldHint values.

Key findings

• The canonical MCP schema defines readOnlyHint=true as meaning the tool does not modify its environment, with a default of false; it defines idempotentHint=true as meaning repeated calls with the same arguments have no additional environmental effect, with a default of false. (S1)
• The schema states that idempotentHint is meaningful only when readOnlyHint is false, and that all ToolAnnotations are hints that may not faithfully describe behavior; untrusted-server annotations must not drive tool-use decisions. (S1)
• The official MCP maintainer guidance explains that annotations are optional, use pessimistic defaults, and should inform preflight UX rather than serve as enforcement; it recommends accurate values for read-only and idempotent behavior. (S2)
• The official filesystem server maps pure reads to readOnlyHint=true, create_directory to readOnlyHint=false plus idempotentHint=true because re-creating the same directory is a no-op, write_file to idempotentHint=true but destructiveHint=true because it can overwrite, and edit_file to idempotentHint=false because re-applying can fail or double-apply. (S3)
• The filesystem server sets openWorldHint=false for local filesystem tools, illustrating that read-only/write and external-world interaction are separate dimensions. (S3)

Known limitations

• The MCP schema defines these fields as optional hints and warns that they may not faithfully describe behavior; clients must not make tool-use decisions from annotations received from untrusted servers.
• idempotentHint is meaningful only when readOnlyHint is false, so it is not a second required label for read-only tools and does not create an additional guarantee for them.
• The annotations do not provide authorization, sandboxing, exactly-once execution, transactional rollback, or protection against hidden downstream side effects; those properties require host and server controls.
• Whether an external API, audit trail, cache, metric, webhook, or other downstream effect counts as an environmental modification depends on the deployed implementation and its contract; the schema alone does not resolve that boundary.

Obsolete approaches

• Do not label every query idempotent as a substitute for accurately declaring readOnlyHint; MCP makes idempotentHint meaningful only for non-read-only tools.
• Do not equate a stable or repeatable response with an idempotent environmental effect.
• Do not use readOnlyHint=true as proof that a tool is safe to auto-approve, authorized, private, or free of external-world interaction.
• Do not leave a mutating tool at optimistic annotations merely because the common path is harmless; account for overwrites, deletes, retries, and downstream calls.

Negative results

• The MCP schema does not define annotations as enforceable guarantees or as a substitute for access control and runtime validation.
• The schema does not define a universal retry protocol, deduplication key, rollback rule, or exactly-once guarantee for idempotent tools.
• The official filesystem mapping demonstrates per-operation distinctions but does not generalize that every write with a stable resource name is idempotent.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• This is documentation and official-repository guidance only; no MCP server was invoked, no handler was inspected in a live deployment, and no independent reproduction was performed.

What remains unknown

• The actual environmental effects of any particular tool still require review of its handler, downstream APIs, credentials, persistence, logging, and deployment configuration.
• The retry behavior and confirmation policy of a particular MCP client or host remain client-specific; the annotations do not force a client to auto-approve or retry.
• For tools that partially complete work before failing, the application-specific deduplication, compensation, and recovery contract must be established separately.
• The operational boundary for incidental effects such as audit logs, billing records, rate-limit counters, caches, and webhooks is not settled by the generic MCP annotation schema.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Schema Reference - Model Context Protocol ToolAnnotations · official_documentation · accessed 2026-09-22
• S2 Tool Annotations as Risk Vocabulary: What Hints Can and Can’t Do - Model Context Protocol Blog · maintainer · accessed 2026-09-22
• S3 MCP Filesystem Server README - ToolAnnotations · official_repository · accessed 2026-09-22