MCP tool hints: interpret defaults before approval or retry

Two hints do not apply to a read-only declaration

A founder comparing Model Context Protocol (MCP) tools may see read-only and idempotent labels together and treat each as a reason to approve a call. The schema limits that reading: destructiveHint and idempotentHint are meaningful only when readOnlyHint == false.[5][6] For a read-only declaration, neither supplies an additional applicable assurance about mutation.

First interpret the declaration; then establish what the operation can read, change or disclose. A private lookup followed by an additive external message can disclose information without any deletion. Evaluate that information path rather than counting reassuring labels.

The official version index captured on 7 October identifies 2026-07-28 as current.[7] The full ToolAnnotations sections have identical extracted text in that edition and 2025-11-25.[5][6] This comparison does not cover the whole protocol or establish which revision a deployed client supports.

What each hint actually declares

Tool.annotations is optional, as are all four boolean behavioral fields. Both captured editions give the defaults and applicability below.[5][6] These hints describe a tool definition; they are distinct from resource or content annotations.

When all four fields are omitted, their defaults are false, true, false and true in the order shown. With readOnlyHint: true, however, destructiveHint and idempotentHint are inapplicable; do not treat their omitted defaults as active mutation characteristics. The openWorldHint default applies independently.[5][6] Defaults describe how to interpret missing metadata, not what a tool has actually done.

All ToolAnnotations properties, including a display title, are hints rather than guaranteed descriptions. Both Tools editions say clients MUST consider them untrusted unless they come from trusted servers.[2][3][5][6] Trusted provenance makes a declaration worth considering. It does not enforce permission or guarantee an outcome.

Read-only, additive and closed-domain answer different questions

readOnlyHint concerns changes to the tool’s environment. It does not classify a returned record as public or make customer-authored text trustworthy. destructiveHint: false describes additive updates: an outbound message can disclose information without deleting anything. Those distinctions are our interpretations of the schema, not observed incidents.[5][6]

openWorldHint describes the interaction domain. The schema contrasts a web search tool with a memory tool; it does not define a firewall or certify closed-domain content as trusted.[5][6] The 16 March 2026 MCP explanation notes that deployment context affects what counts as external. Network and sandbox guarantees need actual controls, not a boolean label.[1]

Simon Willison’s 16 June 2025 framing combines access to private data, exposure to untrusted content and the ability to communicate externally. The MCP blog applies it to sessions containing multiple tools.[4][1] A closed-domain customer note can supply private data and untrusted customer text at once; a second, additive tool can supply the external route.

This framing is not a controlled study or an estimate of how often such combinations are exploited. Our recommendation is to inspect reachable data flows and enforced restrictions. Blocking outbound use for one private-note path can remove that route, without establishing whole-system security.

Completed hypothetical evaluation: lookup and draft, not send

This fictional evaluation assumes a trusted internal lookup and an external message tool. A user permits reading one customer’s support note to prepare a local draft, not sending it. The note may contain customer-authored text. Assume an enforced customer-scope read restriction and a control that prevents external sending on this draft-only path. No real note, recipient, provider or tool was used; the controls are assumptions, not verified product features.

Changing only the sender’s declaration to idempotentHint: true changes its declared repeat behavior, not permission to send. It also does not prove that a first message was delivered.[5] A separately established implementation contract may change the retry choice without changing the permission choice.

The lookup is the positive automation case. Credible provenance, bounded access, appropriate permission and controlled handling of returned content may support automatic routing within the assumed limits. Requiring a new dialog for every read-only query is not our recommendation. Here, the enforced draft-only boundary prevents external disclosure; the read-only label does not.

Idempotency is about additional effects, not identical answers

idempotentHint: true declares that repeated calls with the same arguments have no additional effect on the environment.[5][6] It does not promise identical answers, a successful first execution or permission to act. Changing arguments falls outside that description.

The 16 March 2026 blog lists “Safe to retry on failure” as an example client behavior.[1] That shorthand does not turn the hint into a guarantee. The Tools document also discusses self-correction and retries with adjusted parameters after tool errors.[2] Neither passage establishes that an external effect never occurred or that a changed call is covered by the original hint.

For a consequential external effect with an ambiguous outcome, our proposed rule is to establish the actual provider/application outcome and the implementation’s repeat contract before automatic repetition. That contract must explain what another call can do and how it handles uncertain outcomes; a separately established contract that safely covers the ambiguity may itself justify repetition. No such implementation was evaluated here. Unknown outcome does not mean failure or permission to send again.

A proposed process for selecting tools

Hints can help clients choose confirmation and routing behavior. The historical MCP explanation also describes graduated trust and policy-engine uses.[1] For tool selection, we propose the following process; it is not a new set of MCP MUST requirements.

• Interpret the declaration. Record the version, explicit values and defaults. Apply destructiveHint and idempotentHint only when readOnlyHint == false; keep missing metadata distinct from measured behavior.
• Establish provenance and reachable effects. Identify why the server definition is credible in this deployment, which records the operation can access, what it can change and where data can go. Installation or authentication alone does not establish those boundaries.
• Evaluate the combined path. Locate private inputs, untrusted content and available communication routes, then identify the enforced access, action and disclosure controls. Returned content cannot supply new user authority.
• Decide approval and repetition separately. Route automatically only within established permission and controls. For consequential unresolved effects, obtain outcome and repeat evidence rather than deriving a resend policy from a hint.

The current Tools contract separately says servers MUST validate inputs, implement proper access controls, rate limit invocations and sanitize outputs. Client confirmation for sensitive operations, input visibility, result validation, timeouts and audit logging are SHOULD guidance.[2] The interaction model recommends a human able to deny invocations but mandates no particular interface.[2] A confirmation dialog is not server enforcement, and these recommendations are not a universal per-call dialog mandate.

Evidence that could change the decision includes version-specific host/server documentation, implemented data and destination restrictions, the authorization decision point, and a repeat contract covering the workload’s ambiguity. If a consequential boundary remains unknown, hold that automation decision rather than every useful read-only operation.

Method, source dates and what remains unmeasured

We compared the full ToolAnnotations sections in the two schema editions, checked optionality, trust and control passages in both Tools pages, and read the official version index. Historical explanatory sources provide context for hint use and tool composition.[1][2][3][4][5][6][7] This is a selected documentary comparison, not a statistical sample, compatibility test or causal estimate.

Primary pages were captured on 7 October 2026 KST. The MCP explanatory post was published on 16 March 2026; Willison’s framing on 16 June 2025. Documentation publication/update dates were not established. The version index redirected to /docs/2026-07-28/learn/versioning and says current revisions may receive compatible changes.[7] An edition identifies a protocol revision, not a page publication or rollout date.

The MCP blog, Tools pages, schemas and index are one publisher family: complementary documentary evidence, not independent empirical confirmations. Willison supplies analytical framing, not measured deployment validation. The March blog’s adoption, client-prevalence and open-proposal claims are not asserted as current facts.

No account was connected, credential collected, SDK installed, real tool invoked or attack attempted. Annotation truthfulness, host/server support, control enforcement, delivery/retry behavior, adoption, exploit prevalence and business outcomes remain unmeasured, not zero. The documented semantics support the findings; the adoption process and completed hypothetical decision are our synthesis.