The tool says read only. The server wrote that itself.

// the badge travels with the tool

When a client lists a server's tools, each one comes back with a name, a description, an input schema and, optionally, a block of annotations. The spec's own definition is short:

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. default: true (meaningful only when readOnlyHint == false) idempotentHint If true, calling the tool repeatedly with the same arguments will have no additional effect on its environment. default: false (meaningful only when readOnlyHint == false) openWorldHint If true, this tool may interact with an "open world" of external entities. default: true title A human-readable title for the tool.

Every one of those fields is set by the server. There is no registry that checks them, no client-side test that confirms a readOnlyHint tool really is read only, and no protocol step where anyone other than the server gets a say. A badge is a sentence the server wrote about itself.

Hints, and the spec's own word for them

The schema's doc comment on ToolAnnotations is unusually blunt, and the parenthesis is the part people miss:

NOTE: all properties in ToolAnnotations are hints. They are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like title). Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.

Even the friendly name on the dialog is self-reported. A tool named delete_files can carry the title "Clean workspace", and the title is exactly as verified as the badge next to it — which is to say, not at all.

The normative line on the Tools page uses the strongest wording the spec has:

For trust & safety and security, clients MUST consider tool annotations to be untrusted unless they come from trusted servers.

Note the condition. This is not "annotations are useless". From a server you already trust — one you wrote, one you audited — they are ordinary, useful metadata, and a client is entitled to use them. The claim is about the trust boundary: a label cannot make a server trustworthy, because the label is the server's own.

What a human actually clicks on

Picture the confirmation dialog. It has a title, maybe a badge, and — if the client is doing its job — the arguments the call is about to be made with. Only one of those three is not a claim.

Clean workspace ← title: a hint read only ← badge: a hint { "path": "~/Documents", ← the act "recursive": true }

The spec's guidance for clients points at the third thing, not the first two. Under its user-interaction model, applications SHOULD "present confirmation prompts to the user for operations, to ensure a human is in the loop", and under security considerations, clients SHOULD:

Show tool inputs to the user before calling the server, to avoid malicious or accidental data exfiltration.

So the control the spec endorses is the arguments in front of a person. Approve what the call is about to do. If your client only shows you the badge, that is the thing to change — and until it does, the badge is telling you what the server would like you to believe.

The defaults point in the safe direction

There is a quieter fact in the defaults table above. Absent any annotation, a tool is assumed to write (readOnlyHint: false), and a writing tool is assumed to be destructive (destructiveHint: true). Silence is treated as dangerous.

Which means a badge only ever moves a tool in one direction: from "assume the worst" to "trust me, it's fine". The only reason to set readOnlyHint: true is to make a client relax. That is legitimate from a server you trust and is precisely the move a bad one would make.

One care point if you build servers: the two write-side hints are only meaningful when readOnlyHint is false. A tool marked read only with destructiveHint: true is not a warning, it is noise — the spec says the field is not meaningful in that state.

Not the hint your own server writes

Two neighbouring ideas, kept deliberately out of this one.

Idempotent tools covers the hint from the other side of the boundary: when you set idempotentHint on your server, the flag advertises a property, it does not build it — you still do the dedup in your handler. That is a hint failing to implement. This page is a hint failing to be trustworthy, which is a different failure with a different fix.

Tool descriptions is about the description field, which the model reads to decide whether to call a tool. Annotations are read by the human (and the client) to decide whether to allow it. Different field, different reader, different decision.

And if you were hoping to key trust on which server sent the annotation: the spec notes the server name from serverInfo "is not guaranteed to be unique across servers and SHOULD NOT be relied upon for disambiguation" — the same problem two servers, one tool name runs into. Trust is a decision you make when you install a server, not a field you read off it afterwards.

Sources: Model Context Protocol specification (draft), Server → Tools (User Interaction Model, Tool data type, Security Considerations); ToolAnnotations in schema/draft/schema.ts. Verified 2026-09-16. This is the draft revision; wording may change before it is stamped.

One concept a week. Free.

The deeper, copy-paste version of each ToolCall short — in your inbox.

// total: 0.00 · spam: void · unsubscribe: one click