Wiki · Concept · Last reviewed July 10, 2026

MCP Tool Annotations

MCP tool annotations are optional metadata on Model Context Protocol tool definitions that describe expected tool behavior for client user interfaces, risk triage, and audit records. They are useful hints, not authorization, sandboxing, or proof that a tool is safe.

Category: Concept Published: June 25, 2026 Modified: July 10, 2026 Last reviewed: July 10, 2026 Tags: MCP, Tool Use, AI Agents, Security, Governance

Snapshot

Definition

MCP tool annotations are metadata fields attached to a Model Context Protocol tool definition. As of this review on July 10, 2026, the MCP specification site lists version 2025-11-25 as the latest version, and its schema reference defines a ToolAnnotations interface with title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The same reference states that every property in ToolAnnotations is a hint, not a guaranteed description of behavior.

The important boundary is that an annotation describes what the server claims about a tool; it does not enforce the claim. A tool marked readOnlyHint: true can still write if the implementation is malicious, buggy, compromised, or broader than its descriptor. Real enforcement belongs in MCP Authorization, credentials, sandboxing, input validation, output validation, network controls, approval gates, and audit trails.

That makes annotations part of governance evidence. They help a client explain why it asked for confirmation, allowed a retry, warned about deletion, or treated returned content as untrusted. They should not be the only reason a tool is allowed to run.

How It Works

An MCP server exposes tools that can be listed and called by a client. The tools specification describes MCP tools as model-controlled: a language model can discover and invoke them automatically according to context and the user's prompt, while implementations design their own user interface and approval flow.

A tool definition can include a programmatic name, display title, description, icons, input schema, optional output schema, execution metadata, and annotations. In the schema reference, readOnlyHint defaults to false, destructiveHint defaults to true, idempotentHint defaults to false, and openWorldHint defaults to true. Absent annotations do not mean safe; the defaults are deliberately conservative for write risk and open-world exposure.

A well-behaved client can use annotations to improve displays and preflight decisions. A destructive, non-idempotent, open-world tool should usually trigger clearer confirmation, tighter logging, more skepticism about returned content, and stronger review before a model can combine it with sensitive data or write-capable tools.

The annotations live beside, not inside, execution controls. The 2025-11-25 schema also defines execution.taskSupport for task-augmented execution, but that execution metadata is different from risk annotations. A long-running tool can still be read-only or destructive; a read-only annotation says nothing by itself about duration, cancellation, authorization, or result trust.

Annotation Semantics

title. A human-readable tool title for display. It can improve user interfaces, but it is still supplied by the server and can mislead if the server is untrusted.

readOnlyHint. If true, the tool claims not to modify its environment. This is useful for lowering friction only when the server is trusted and the implementation is constrained. It is unsafe as a standalone permission check.

destructiveHint. If true, a write-capable tool may perform destructive updates; if false, it claims to perform only additive updates. The field is meaningful only when readOnlyHint is false. Deletion, overwriting, privilege changes, purchases, publishing, or irreversible state changes should be treated as high-risk regardless of optimistic wording.

idempotentHint. If true, repeated calls with the same arguments claim to have no additional effect. This matters for retries after network failure or timeout. Clients should still use idempotency keys, transaction checks, and downstream safeguards for actions that send, charge, delete, deploy, or change permissions.

openWorldHint. If true, the tool may interact with external entities outside a closed domain. Web search, email, issue trackers, repositories, calendars, chats, and arbitrary APIs are common open-world surfaces. Returned content should be treated as untrusted data that may contain prompt injection, tracking links, stale claims, or instructions aimed at the model.

Boundary Tests

Current Context

As of July 10, 2026, the official MCP schema reference still lists ToolAnnotations in the 2025-11-25 specification and identifies that version as the latest. The older 2025-03-26 changelog records the addition of comprehensive tool annotations for describing behavior such as read-only or destructive tools. The March 16, 2026 MCP blog post frames the four boolean hints as a basic risk vocabulary and says existing annotations are worth using, while keeping hard guarantees in deterministic controls.

The current direction is toward richer governance, not blind trust. The MCP blog notes open questions about whether annotations should apply to tool responses and whether any should be evaluated at runtime rather than declared statically. It also states that if a proposal's value depends on the annotation being true, the right layer is authorization, transport, or runtime, not ToolAnnotations.

Security guidance has become more explicit around the same trust boundary. The MCP tools specification says there should always be a human in the loop with the ability to deny tool invocations, and that applications should show exposed tools, indicate tool invocation, and present confirmation prompts for operations. The official MCP security best-practices page covers confused-deputy attacks, token passthrough, server-side request forgery, session hijacking, local MCP server compromise, and scope minimization. OWASP's MCP Top 10 identifies tool poisoning and tampered manifests or schemas as a supply-chain attack pattern.

Why It Matters

Tool annotations matter because agent systems often decide from machine-readable context. A human may never read the full schema, but the model, client, approval UI, and logging system may all rely on tool metadata to decide what to show, what to permit, and what to remember.

That gives annotations a double role. They reduce ambiguity by telling the client that a tool is read-only, destructive, repeat-safe, or externally connected. They also become a failure point if a malicious, stale, or compromised server lies. A false readOnlyHint is not just bad documentation; it can soften the confirmation path for a tool that changes the world.

For institutional use, the strongest reading is conservative: annotations should shape user experience, triage, and audit labels, while actual enforcement lives in authorization scopes, runtime sandboxing, server-side policy, validation, and human approval.

Failure Modes

False safety labels. A server can mark a tool read-only while the implementation writes, sends, purchases, publishes, deletes, or changes permissions.

Schema and descriptor poisoning. OWASP treats tampered schemas, manifests, and metadata as a supply-chain style attack because agents may execute valid-looking calls under a malicious contract.

Runtime drift. A tool can be reviewed with one description or annotation set, then return with changed metadata after an update, reconnect, registry change, or compromised deployment.

Open-world underlabeling. A tool that reaches websites, email, repos, chat, documents, or external APIs may bring untrusted content back into the model loop.

Client inconsistency. Different clients may honor annotations differently. One client may ask for confirmation, another may only display a label, and another may ignore missing annotations entirely.

Governance Requirements

Governed deployments should treat annotations as part of the tool manifest and supply chain. Store the server identity, tool name, schema version, annotations, owner, approval decision, and review date. Diff those fields when a server refreshes or a registry entry changes.

Clients should display annotation-driven risk honestly: read-only versus write-capable, destructive versus additive, idempotent versus repeat-sensitive, closed-domain versus open-world. Sensitive operations should still show arguments and expected side effects before execution.

Authorization should not depend on a hint. A tool that claims to be read-only still needs least-privilege credentials, and a tool that claims to be closed-domain still needs result validation before its output enters the model context.

Audit logs should preserve the annotations the model and user actually saw, not only the final tool call. If an incident turns on a misleading label, the investigation needs historical metadata, server version, client behavior, and approval path.

Minimum Annotation Record

A governed MCP client should preserve enough information to reconstruct the annotation state at the time a tool was offered or invoked.

Source Discipline

Claims about MCP annotations should name the MCP specification version. The 2025-11-25 tools and schema pages are the primary sources for the current interface, defaults, and trust warning reviewed here. The 2025-03-26 changelog is the primary source for when comprehensive tool annotations were added.

Separate specification from implementation. The spec defines fields, while a client decides how to display, confirm, log, retry, sandbox, or enforce tool use. A vendor UI, SDK helper, or registry policy may add stronger behavior, but that is a product claim, not a protocol guarantee.

Security claims should separate soft metadata from hard controls. For annotations, use official MCP spec pages and MCP blog posts. For tool poisoning, schema tampering, and supply-chain risk, prefer OWASP MCP Top 10, official MCP security guidance, CVEs, incident reports, and reproducible security research. For authorization claims, cite the MCP authorization specification and OAuth sources rather than the annotation page.

Spiralist Reading

MCP tool annotations are tiny governance texts written for machines.

They say: this action is only looking, this one may change the archive, this one touches the open world. The danger is not that such labels exist. The danger is treating the label as the law.

The Spiralist discipline is to keep the label visible without worshiping it. The boundary has to be made of permissions, review, logs, and accountable humans.

Open Questions

Sources

Return to Wiki