MCP tool annotation

What is MCP tool annotation?

MCP tool annotation is metadata attached to a Model Context Protocol tool that describes how the tool behaves, including flags like read-only, destructive, and idempotent. These hints help MCP clients decide when to auto-run a tool, request approval, or treat a call more cautiously. (modelcontextprotocol.io)

Understanding MCP tool annotation

In practice, MCP tool annotation sits alongside the tool definition and gives the client more context about risk and side effects. The current MCP schema defines tool annotations as optional fields for clients, including readOnlyHint, destructiveHint, and idempotentHint, and notes that they are only hints, not guarantees. (modelcontextprotocol.io)

That distinction matters. A well-annotated tool can make an agent experience smoother, because a client can treat safe-looking calls differently from calls that may change state or need confirmation. In other words, the annotation is not the tool itself, it is guidance for the host application about how to manage permissions and user trust. (modelcontextprotocol.io)

Key aspects of MCP tool annotation include:

1. Read-only hint: signals that the tool does not modify its environment.
2. Destructive hint: indicates the tool may perform destructive updates, but only when the tool is not read-only.
3. Idempotent hint: tells clients that repeated calls with the same arguments should have no additional effect, again only when the tool is not read-only.
4. Client guidance: helps hosts decide whether to auto-run, defer, or ask for approval before execution.
5. Non-binding metadata: the spec treats these values as hints, so clients should not rely on them blindly.

Advantages of MCP tool annotation

1. Safer automation: clients can distinguish low-risk tools from tools that can change state.
2. Better user experience: read-only actions can feel faster because hosts may reduce confirmation prompts.
3. Clearer tool design: developers are encouraged to think about side effects and repeatability up front.
4. Improved agent routing: hosts and orchestrators can apply different policies based on the annotation.
5. More predictable workflows: teams can standardize how tools are exposed across different MCP servers.

Challenges in MCP tool annotation

1. Hints can be wrong: the spec says annotations are not guaranteed to faithfully describe behavior.
2. Policy depends on the client: one MCP host may enforce stricter approval rules than another.
3. Ambiguous side effects: some tools read and write in subtle ways, which makes classification harder.
4. Idempotence is contextual: repeated calls may behave differently depending on backend state or external systems.
5. Security still needs guardrails: annotation helps with policy, but it is not a substitute for real access control.

Example of MCP tool annotation in action

Scenario: a team exposes three MCP tools in an internal assistant, one for searching documents, one for creating tickets, and one for deleting files.

The document search tool is marked readOnlyHint: true, so the client can surface it with minimal friction. The ticket creator might be marked non-read-only and idempotent if repeated calls with the same payload should not create duplicates. The delete tool would likely be marked destructive, which gives the host a strong signal to ask for confirmation before execution. (modelcontextprotocol.io)

That setup helps the assistant stay fast for safe lookups while slowing down for actions that can alter data. The result is a better balance between autonomy and control.

How PromptLayer helps with MCP tool annotation

PromptLayer helps teams manage the prompts, tool calls, and evals around MCP-enabled workflows, so annotated tools can be tracked and reviewed as part of a broader LLM system. As MCP integrations grow, having visibility into when tools are called, how they behave, and where human review is needed becomes much easier to operationalize with PromptLayer.

Ready to try it yourself? Sign up for PromptLayer and start managing your prompts in minutes.