Annotations

Annotations (often referred to as Hints) in the Model Context Protocol (MCP) are optional metadata fields attached to tools. They provide critical context to the MCP Client (like an AI assistant or IDE) about how a specific tool behaves, helping the client build safer and more intuitive user experiences.

While servers provide the execution logic, annotations help clients decide *how* to present that tool to the user—for example, automatically running safe tools while asking for explicit permission before executing destructive ones.

Key Tool Annotations

According to the latest MCP specification, tools can declare several boolean hints to describe their operational nature:

• → readOnlyHint: Indicates whether a tool strictly performs read operations without modifying its environment or returning differently shaped state. If true, clients can often safely auto-approve the execution of this tool.
• → destructiveHint: Signals that a tool will perform destructive updates, delete data, or have significant, irreversible side effects. Clients typically mandate strict user confirmation (human-in-the-loop) before executing tools with this annotation.
• → openWorldHint: Specifies if the tool interacts with external, unpredictable entities like public web APIs, external databases, or the open internet. This helps clients understand that the tool's results may be non-deterministic or reliant on external availability.
• → idempotentHint: Indicates if repeated calls to the tool with the exact same arguments will yield the same result without causing additional side effects.

Why are Annotations Important?

MCP is designed to bridge LLMs with real-world infrastructure. Because LLMs can autonomously decide to call tools, Annotations form the backbone of the safety and governance model on the client side.

By utilizing hints like destructiveHint, an MCP client ensures that an AI cannot autonomously drop a database table or send a binding email without a human user explicitly clicking "Approve" in the UI.

Questions & Answers

What are annotations in the context of the Model Context Protocol?

Annotations (or hints) are optional metadata fields included in the definition of an MCP tool. They inform the client about the tool's behavior, such as whether it is safe to run automatically or if it makes irreversible changes.

Does `readOnlyHint: true` guarantee safety?

While readOnlyHint tells the client that the tool *intends* to only read data, it is ultimately up to the MCP Server implementation to ensure that the code backing the tool does not actually mutate state. Annotations are hints for the client's UI/UX, not cryptographic security boundaries.

How do annotations improve tool selection by AI clients?

By providing descriptive hints (openWorldHint, idempotentHint), annotations allow AI clients to more intelligently manage the tool execution lifecycle, provide better loading states, and enforce appropriate security boundaries (like pausing execution to ask for human approval for a destructiveHint).