Tool annotations (MCP)
What is Tool annotations (MCP)?
Tool annotations are optional Model Context Protocol metadata, like readOnlyHint and destructiveHint, that describe a tool's expected effects so a client can decide how much friction to apply before a call runs -- hints the specification treats as untrusted, not a security boundary. AdminKit's MCP endpoint check infers a similar severity signal from each tool's own description.
By AdminKit team, Netbase JSC · Updated
Tool annotations are optional metadata a Model Context Protocol server — part of the protocol Anthropic introduced to standardize how applications connect context and tools to an LLM — attaches to a tool’s definition — hints such as readOnlyHint, destructiveHint, idempotentHint and openWorldHint that describe what kind of effect calling the tool is expected to have. A client or gateway can use these hints to decide how much friction to apply before a call goes through, for instance requiring explicit confirmation before a tool flagged as destructive runs, while letting a read-only one proceed more freely. That confirmation step is the control OWASP’s Top 10 for LLM Applications recommends against excessive agency: human-in-the-loop approval of high-impact actions before they are taken. The specification is explicit that annotations are untrusted hints, not a security boundary: a server can declare any value it wants, including a false readOnlyHint on a tool that actually deletes data, so a client that treats annotations as guaranteed rather than advisory is trusting the same server it may not have otherwise vetted. Because annotations are only self-declared, they don’t protect against a more active threat like tool poisoning, where a tool’s description itself is crafted to manipulate the calling agent.
AdminKit groups tool annotations (MCP) under its AI agents & MCP cluster — browse the AdminKit glossary index for other related terms.
Frequently asked questions
Are MCP tool annotations a security boundary?
No -- the specification is explicit that annotations are untrusted hints, not a security boundary, since a server can declare any value it wants.
What are two examples of MCP tool annotation hints?
readOnlyHint and destructiveHint, which describe whether a tool is expected to only read data or to make a destructive change; idempotentHint and openWorldHint are two others.
Can a server declare a false readOnlyHint on a destructive tool?
Yes -- nothing enforces accuracy, so a client that treats annotations as guaranteed rather than advisory is trusting the same server it may not have otherwise vetted.