tool annotations
Also written annotations
Tool annotations are optional hints on a tool object describing how it behaves: whether it only reads, whether repeating it is safe, whether its effects are destructive, and whether it touches the open world. The specification requires clients to treat them as untrusted unless the server is trusted.
What are tool annotations?
Annotations are a small object of behavioural hints attached to a tool. They describe the kind of operation the tool performs rather than its arguments.
The common ones cover whether the tool is read-only, whether it is idempotent, whether its effects are destructive, and whether it reaches systems outside a closed set.
Why does the specification call them untrusted?
Because they are the server's own claims about itself, and nothing verifies them. The specification is explicit that a client "MUST consider tool annotations to be untrusted unless they come from trusted servers".
A tool annotated read-only can still write. The annotation is a hint for presentation and caution, never a guarantee, and a client that gates a confirmation prompt purely on the annotation has trusted a stranger's assertion.
How widely are they used?
Widely enough to be worth reading, and not consistently enough to require. Annotations appeared on 262 of the 288 tools we read on 5 August 2026, which is 91%.
That makes them the most common optional field by a wide margin: title managed 10.1% and outputSchema 5.6% on the same sample.
Example
A documentation search tool would reasonably annotate itself read-only and idempotent, since calling it twice changes nothing. A tool that deletes a record would annotate itself destructive, and a careful client would surface a confirmation before calling it. Both annotations are written by the same server author, which is precisely why the specification tells clients not to rely on them for safety decisions.