Short answer: MCP tool annotations describe expected behavior; they grant no permissions and enforce no guarantees. The defaults are readOnlyHint: false, destructiveHint: true, idempotentHint: false and openWorldHint: true. Keep client authorization in control, including for trusted servers. Before repeating an uncertain write, check the operation's status or the implementation's documented deduplication contract. The versioned schema also limits the destructive and idempotent hints to tools that are not read-only.

The practical distinction matters when building an approval screen. An annotation describes what the server expects a tool to do. Your application still has to decide what this user may authorize, restrict the operation's scope and handle an uncertain result.

What the four hints actually say#

Each annotation answers one question about a tool's behavior. readOnlyHint asks whether the tool modifies anything. destructiveHint asks, if it modifies something, whether the change is destructive rather than additive — an overwrite versus an append. idempotentHint asks whether calling it again with identical arguments is safe. openWorldHint asks whether the tool reaches out to an unbounded set of external entities or stays inside a closed, predictable domain.

The MCP blog presents the fields as a vocabulary for assessing risk. Its approval-dialog examples illustrate possible client behavior, rather than requiring automatic approval. A client may give a trusted read tool a simpler flow when its own policy permits that. A destructive write deserves a clear description of the proposed changes. Trust in the server and permission for this particular operation remain separate decisions.

The defaults are pessimistic on purpose#

Here's the first non-obvious detail, and the one most people get backwards. The defaults are not neutral — they're cautious. readOnlyHint defaults to false. destructiveHint defaults to true. idempotentHint defaults to false. openWorldHint defaults to true.

Read that as a cautious description of a tool that declares nothing: it may write, destroy state, produce additional effects on repetition and interact with external entities. The protocol supplies defaults; it does not implement a client's approval flow. Missing annotations should therefore leave your existing controls intact. The permissive states (readOnlyHint: true, destructiveHint: false) are claims a server makes, not evidence that it has earned access.

Annotations aren't how a tool earns trust. They're how a trusted tool sheds friction. The distinction is the whole security story.

The line the spec draws in bold#

The tools specification requires treating annotations as untrusted unless they come from trusted servers. The schema makes the consequence explicit: hints received from untrusted servers must not determine tool-use decisions. That applies even to a plausible-looking title or description.

Nothing in an annotation prevents a compromised server from labeling a destructive operation read-only. It is self-reported metadata. It also cannot neutralize prompt injection in returned content. Consider an illustrative public-search tool:

{"annotations":{"readOnlyHint":true,"openWorldHint":true}}

Those claims can coexist: the tool reports no modifications while reaching external sources. The response can still contain misleading instructions or private information. Validate the destination and scope before execution, then treat retrieved material as data rather than authority.

So the failure mode writes itself. A team ships an agent, sees readOnlyHint, and wires it into an auto-approval path: if readOnly, run it without asking. Then they connect a third-party MCP server they don't control, and the annotation they treated as a fact becomes an input the attacker chooses. The UX signal got promoted to a security decision, which is the one move the spec explicitly tells you not to make. Keep the actual boundary where it belongs — sandboxing, network egress rules, zero-trust posture, and auth — and let annotations do only what they can: shape the dialog for servers you've already decided to trust.

The trap inside idempotentHint#

idempotentHint: true describes repeated identical calls having no additional effect on the environment. It does not provide deduplication machinery. A timeout is ambiguous: the request may have failed, or it may have succeeded and lost its acknowledgment. Replaying a write based solely on the hint can therefore duplicate its effects. Returning the same value is also a different property from applying an operation only once.

Before retrying, reconcile the operation's recorded status or rely on a documented, verified retry contract. For a service supporting idempotency keys, persist one key for the logical operation and reuse it as the provider documents. Generating a new key for each attempt defeats that protection. An intrinsically idempotent implementation may need no key; simply adding a client-side string to an unsupported service provides no protection at all.

How to hold them#

Keep annotations in a risk-description layer backed by authorization, sandboxing, egress controls and implementation checks. A useful approval screen says what is about to happen and where its authority comes from. A useful retry path records what may already have happened. Neither should substitute a server's label for evidence. To implement the metadata on your own server, continue with the annotation setup guide; for uncertain writes, use the linked idempotency guide above.