MCP Tool Behavior Annotations and Trust Limits

What tool behavior annotations are

Tool behavior annotations are optional metadata in an MCP tool definition. They let a server describe the effects a client should expect before the tool runs: whether it only reads, whether its writes may destroy data, whether repeating a call adds another effect, and whether it interacts with external entities.

The MCP Tools specification dated 2025-11-25 defines tools as model-controlled but does not prescribe one client interface. It recommends that applications show which tools are available, indicate when a tool runs, and give a human the ability to deny an invocation. Annotations can make those interfaces more informative. They do not grant permission or constrain what the server can actually do.

That distinction matters across MCP clients in an IDE or desktop assistant. Clients can present approvals differently while receiving the same server-supplied annotations.

The four behavior hints

The 2025-11-25 MCP schema reference defines four boolean behavior fields under ToolAnnotations. Each is optional and has a specified default.

readOnlyHint

readOnlyHint: true says the tool does not modify its environment. The default is false, so an omitted field must not be interpreted as a read-only declaration.

“Read-only” is narrower than “low risk.” It describes mutation, not disclosure or reach. A tool can read local information and send a query to an external service without modifying either one. The openWorldHint describes that separate dimension.

When readOnlyHint is true, the destructive and idempotent hints are not meaningful under the schema. Both describe the effects of writes, and a read-only tool claims not to write.

destructiveHint

destructiveHint: true says the tool may perform destructive updates. The default is true, and the field is meaningful only when readOnlyHint is false.

A value of false does not mean the tool makes no changes. It means the tool claims its updates are additive rather than destructive. A “create record” tool could therefore be non-read-only and non-destructive, while a tool that replaces, deletes, or otherwise damages existing state should be marked destructive when that behavior is possible.

The word “may” is important. A tool whose ordinary call is additive but whose optional argument can overwrite existing state still has destructive behavior available. An approval interface should explain the risk using the actual arguments, not reduce the decision to the annotation alone.

idempotentHint

idempotentHint: true says that calling the tool repeatedly with the same arguments has no additional effect on its environment. Its default is false, and it is meaningful only for a tool that is not read-only.

Idempotence is about repeated effects, not whether the first effect is acceptable. Deleting a named object can be idempotent if subsequent identical calls do nothing further, yet the first call is still destructive. Creating a new object on every invocation is not idempotent, even if each creation is additive.

The condition also requires the same arguments. Changing an identifier, destination, or payload creates a different call, so the hint says nothing about the combined effect. A client may use a trusted idempotence hint to explain replay risk, but an untrusted hint is not a sound basis for automatic retries.

openWorldHint

openWorldHint: true says the tool may interact with an open world of external entities. The default is true. The schema gives web search as an open-world example and a memory tool as a closed-world example.

This field is independent of mutation. A search tool can be read-only and open-world. A tool that writes only to a bounded local store can be non-read-only and closed-world. The annotation helps a client explain that a call may cross the server’s closed domain, but it does not identify every destination, prove confidentiality, or authorize network access.

Annotations are untrusted hints

The server supplies annotations as part of its tool definitions. The same server also implements the operation being described. An annotation therefore reports the server’s claim about its own behavior; it is not an attestation produced by an independent authority, and it does not technically restrict the implementation.

The specification is explicit: clients must consider tool annotations untrusted unless they come from a trusted server. A server can be mistaken, out of date, compromised, or deliberately misleading. Any of those conditions can produce a tool marked read-only that writes, a destructive tool marked additive, or an open-world tool marked closed-world.

Trust must be established before the annotations influence a security decision. It cannot be inferred from a reassuring tool title, description, or annotation because all of those fields arrive from the same source. This is one reason to decide which MCP servers a project actually needs and record the approved server identity and configuration rather than accepting every discovered server equally.

Even for a trusted server, an annotation describes a tool class rather than proving the behavior of one invocation. Arguments can select a destructive mode or an external destination. The client still needs to evaluate the requested operation against its own policy.

How approval interfaces should use annotations

An approval interface can translate annotations into plain risk information. It can say that a tool claims to be read-only, that a write may replace existing state, that repeating the same request may add another effect, or that the operation may contact external entities. This helps the user understand why approval is being requested.

The interface should also show the verified server identity, tool name, relevant arguments, intended target, and the permissions being exercised. A label such as “read-only” without the server and inputs leaves out the facts needed to judge what will be read and where the information may go.

Annotations should not lower an approval requirement established by trusted configuration. If policy requires confirmation before a particular server accesses a repository, sends data outside the project, or invokes a named tool, readOnlyHint: true is not a reason to bypass that rule. Likewise, destructiveHint: false cannot turn a write into a read; it claims only that the write is additive.

Policy should instead come from inputs the client has verified or controls: the identity of the configured server, the project’s allowlist, the permissions granted to that server, and explicit per-tool or per-operation rules. The annotations can supply explanatory text after that trust decision, not make the decision themselves.

The MCP security best practices dated 2025-11-25 reinforce that separation. They call for server-side authorization logic rather than treating claimed token scopes as sufficient, and recommend progressive, least-privilege scopes. An annotation is not a substitute for either control. For remote servers, binding an access token to its intended MCP server addresses identity and authorization at a different layer from behavior hints.

What server authors should declare

Server authors should set annotations from the broadest behavior a tool permits, not its most common path. A tool that can overwrite when one argument is present may be destructive even when most calls create new data. A tool is idempotent only when repeating the same arguments causes no additional environmental effect. A tool that may contact external entities is open-world even if some invocations stay within a closed store.

Omitting annotations invokes conservative schema defaults: not read-only, potentially destructive, not idempotent, and open-world. Those defaults do not prove that a tool has those behaviors. They tell clients how an absent claim is interpreted and avoid turning missing metadata into an assurance.

What to check next

Behavior annotations answer what a server claims a call may do. They do not describe the response structure; use MCP tool output schemas to validate structured results. For an approval or execution policy, check the configured server identity, granted permissions, tool arguments, and applicable project rules before using annotations to explain the remaining risk.