What do MCP tool annotations actually promise — and why can't a client just trust them?
AdminKit explains what MCP tool annotations actually promise: a Model Context Protocol tool definition can carry readOnlyHint, destructiveHint, idempotentHint and openWorldHint, signaling what calling the tool will do to the world. The specification is explicit that these are hints a server declares about itself, not a guarantee a client can independently verify before trusting them.
By AdminKit team, Netbase JSC · Updated
Key takeaways
- MCP tool annotations are four optional yes/no hints a server attaches to a tool:
readOnlyHint,destructiveHint,idempotentHintandopenWorldHint. There is also an optional displaytitle. - The defaults assume the riskier case. A tool that declares nothing is treated as not read-only, possibly destructive, not idempotent and open-world.
- The specification calls annotations hints. Clients must treat them as untrusted unless the server is trusted, because the server describing the tool is the same server you are trying to judge.
- Use them to shape confirmation prompts for servers you control. Never use them as the reason to skip a human check on a server you don’t.
What are the four hints, and what does each one declare?
The MCP specification’s schema — whose source lives in the Model Context Protocol specification repository — defines ToolAnnotations as an object a server can attach to any tool it lists, alongside an optional title for display:
- readOnlyHint — “If true, the tool does not modify its environment.” Default: false.
- destructiveHint — “If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates.” Meaningful only when
readOnlyHintis false. Default: true. - idempotentHint — “If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment.” Also only meaningful when
readOnlyHintis false. Default: false. - openWorldHint — “If true, this tool may interact with an ‘open world’ of external entities. If false, the tool’s domain of interaction is closed.” The spec’s own example: a web search tool is open-world; a tool that only queries a fixed internal memory store is not. Default: true.
The same facts as a quick reference:
| Hint | Question it answers | Default | Applies when |
|---|---|---|---|
readOnlyHint | Does the tool leave its environment unchanged? | false | Always |
destructiveHint | Can it delete or overwrite, rather than only add? | true | readOnlyHint is false |
idempotentHint | Is a repeat call with the same arguments harmless? | false | readOnlyHint is false |
openWorldHint | Does it reach external entities beyond a closed system? | true | Always |
Why do the defaults lean towards the riskier case?
The defaults are the detail most worth noticing: a tool that declares nothing is treated, by the schema’s own defaults, as not read-only and potentially destructive. Silence isn’t a neutral or safe assumption here — it’s the spec’s way of saying “assume the riskier case until told otherwise.”
In a tool list, annotations sit next to the name, description and input schema. The definition below is illustrative, with an invented tool, but uses the field names from the schema. It describes a ticket-creation tool that writes to an internal system, never deletes anything, and talks only to that one system:
{
"name": "create_ticket",
"title": "Create support ticket",
"description": "Open a ticket in the internal helpdesk with a subject and body.",
"inputSchema": {
"type": "object",
"properties": {
"subject": { "type": "string" },
"body": { "type": "string" }
},
"required": ["subject", "body"]
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
}
}
Each value here is a claim. idempotentHint: false is the server saying a second call opens a second ticket; openWorldHint: false says the tool reaches nothing outside the helpdesk. If the same tool also emailed customers, the accurate value would be true, and only reading the server’s code, or watching what the tool does, would tell you which is correct.
Annotations describe a tool’s declared behavior; they say nothing about the shape of what it returns. A tool result’s structured content — the optional structuredContent field validated against the tool’s own outputSchema — is a separate piece of self-reported tool metadata that needs the same validate-before-trusting treatment, for the same reason: the server declaring the schema is the same server whose annotations you already can’t take at face value.
How do the hints combine for real tools?
Because destructiveHint and idempotentHint only mean something for tools that are not read-only, a handful of combinations cover most tools. The examples are illustrative tool types, not tools from a specific server:
| Kind of tool | readOnly | destructive | idempotent | openWorld |
|---|---|---|---|---|
| Web search | true | — | — | true |
| Query a local notes store | true | — | — | false |
| Append a log entry | false | false | false | false |
| Set a config value to X | false | true | true | false |
| Delete a file | false | true | true | false |
| Send an email | false | false | false | true |
Setting a value is destructive, since it overwrites the previous value, but idempotent, since doing it twice changes nothing more. Sending an email only adds, yet it cannot be undone and reaches the outside world, which is why many clients ask for confirmation on openWorldHint: true tools as well as destructive ones.
Why does the specification call these “untrusted”?
Right next to the field definitions, the schema reference states plainly that annotations “are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like title),” and that “clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.” The MCP specification’s Tools page repeats the same point as a flagged warning: clients “MUST consider tool annotations to be untrusted unless they come from trusted servers.”
This is a textbook instance of what MITRE’s CWE-345, Insufficient Verification of Data Authenticity, describes: accepting self-reported metadata as accurate with no independent way to confirm it actually reflects the tool’s real behavior. The reasoning is the same as for a tool’s name and description: all of it is self-reported by the server exposing the tool, over the same tools/list call AdminKit’s MCP endpoint check sends when probing whether a server requires authentication — see how to read an MCP endpoint check result for what that check actually does. A server that’s already malicious, compromised, or just carelessly written has no protocol-level obligation to declare destructiveHint: true on a tool that deletes records, and nothing in MCP itself catches that mismatch. Annotations formalize the kind of severity signal a careful reader would otherwise have to infer from a tool’s name alone, but they inherit the exact same trust problem: a server you haven’t vetted can say anything it wants about itself.
The same Tools page also says there should always be a human in the loop with the ability to deny tool invocations, and that clients should present confirmation prompts for operations. Annotations can make those prompts smarter. They cannot replace them.
How can a client use annotations from a server it trusts?
For a server you built or have reviewed, annotations are a cheap way to set the level of friction per tool. The policy below is one example of how a client or gateway might map hints to behaviour. It is not part of the specification, and you should tune it to your own risk:
| Declared annotations | Example client behaviour |
|---|---|
readOnlyHint: true, openWorldHint: false | Run without a prompt; log the call |
readOnlyHint: true, openWorldHint: true | Run without a prompt; show which external source was queried |
readOnlyHint: false, destructiveHint: false | Ask once per session |
destructiveHint: true, or nothing declared | Ask every time and show the arguments |
| Any tool from an untrusted server | Ask every time, whatever the annotations say |
The last row is the one that matters. Once a server is untrusted, its annotations drop out of the decision and you are back to the tool’s name, its description and a human reading the arguments.
What does this mean in practice?
Treat annotations the way you’d treat any other claim a server makes about its own behavior:
- From a server you built or fully control, annotations are a useful, low-cost way to drive client-side UX — for example, requiring an explicit confirmation step before any call that isn’t
readOnlyHint: true, rather than prompting on every single call. - From a server you don’t control, read annotations as one input alongside the tool’s name and description, not as a verified fact. A tool named
delete_recorddeclaringreadOnlyHint: trueis a red flag about the server’s trustworthiness in general, not a reason to relax. - Keep a human in the loop for consequential actions regardless of what’s declared — the specification’s own guidance for tool use recommends exactly this, independent of whatever annotations a tool carries. See how to secure an MCP server for the fuller checklist, and what a security gateway adds in front of an MCP server if you’re evaluating a dedicated layer that can enforce confirmation or allowlisting independent of whatever the upstream server claims about itself.
If you run an MCP server, declare annotations accurately on every tool, including the read-only ones. Leaving them out is not neutral: clients fall back to the defaults and treat each tool as destructive and open-world, which usually means more confirmation prompts for your users. Accurate hints are also easier to audit, because a reviewer can compare each declared value with the code behind the tool. When a tool’s behaviour changes, update its annotations in the same change, and treat a mismatch found in review as a bug.
How do annotations relate to other MCP risks?
Annotations are one of several self-reported fields in a tool definition, and the others carry similar risks. A tool’s description can hide instructions for the model, which is the attack described in how to check for MCP tool poisoning. A server that forwards a client’s token to another service creates a different problem, covered in the MCP confused deputy and token passthrough. In each case the fix is the same idea: decide trust from things the server cannot simply declare, such as who runs it, what its code does and what a human approved.
Tool annotations are a real, useful piece of the MCP spec — they just answer “what does this server say it does,” not “what has been independently verified that it does.” The distinction matters most for exactly the servers you’re least sure about, which is precisely when a self-reported hint is least reliable. This guide is part of AdminKit’s AI agents & MCP cluster of guides and tools for securing Model Context Protocol servers.
This guide is general information, not a security audit of your specific network — see our disclaimer for what AdminKit's guidance does and does not commit to.
Frequently asked questions
What are MCP tool annotations, in plain terms?
Optional metadata a server attaches to each tool it exposes, alongside the tool's name and description, describing the expected effect of calling it: whether it only reads data, whether it can destroy something, whether calling it twice with the same input is safe, and whether it reaches outside a closed, predictable system. The Model Context Protocol's schema defines four boolean hints — readOnlyHint, destructiveHint, idempotentHint and openWorldHint — plus an optional display title.
What happens if a server doesn't set any annotations at all?
The defaults matter and lean cautious, not permissive. Per the MCP schema, readOnlyHint defaults to false and destructiveHint defaults to true — meaning a tool with no annotations is assumed capable of destructive changes unless the server explicitly says otherwise with readOnlyHint: true. A client reading an unannotated tool should not assume it's safe just because nothing was declared.
Can a malicious or careless MCP server just lie in its annotations?
Yes, and the specification says so directly: annotations "are not guaranteed to provide a faithful description of tool behavior," and clients "should never make tool use decisions based on ToolAnnotations received from untrusted servers." A server could declare readOnlyHint: true on a tool that actually deletes records, and nothing in the protocol itself stops that — the hint is self-reported, the same way a tool's name and description are.
Does AdminKit's MCP endpoint check show me a tool's annotations?
No. AdminKit's MCP endpoint check calls tools/list and records each exposed tool's name, which is enough to judge an unauthenticated tool list's risk from the name alone (see how to read an MCP endpoint check result) — it doesn't parse or display the annotations object a tool definition may also carry. This guide explains what that metadata means for anyone building a client, gateway or agent that does read it.
If annotations can't be trusted, what's the point of them?
They're most useful as a server's own declared intent when the server is one you built or trust, or as one more signal to weigh — never the only one — when deciding how much friction to add before a call goes through (e.g. requiring explicit confirmation before anything not declared readOnlyHint). Combined with reading the tool's actual name and description, and keeping a human in the loop for consequential actions as the specification itself recommends, annotations add useful context without replacing the judgment a client still has to apply.
Which title does a client show if a tool has several?
The schema sets an order: the tool's own title field first, then annotations.title, then the tool name. Since every one of those is chosen by the server, a friendly display name says nothing about what the tool does; it is still self-reported text.
Want AdminKit to watch this for you?
Free checks tell you the state today. Protective DNS and monitoring tell you when it changes.
Talk to an expert
Huy Nguyen (David), Founder & CEO, Netbase JSC
Ask whether this fix applies to your setup, or get a second pair of eyes on your DNS and mail records.