Skip to content

Tool annotations ​

Optional hints an MCP server attaches to a tool definition, saying whether the tool is read-only, destructive, idempotent or reaches the outside world; clients must treat them as untrusted.

A tool's name and description tell the model what the tool does. Annotations tell the client how risky it is, so the app can decide what to show, confirm or block. The 2025-11-25 schema defines five fields, with defaults for when a hint is missing:

FieldMeaning when trueDefault
title(text) a human-readable namenone
readOnlyHintdoes not modify its environmentfalse
destructiveHintmay perform destructive updates (only meaningful when not read-only)true
idempotentHintrepeating the call with the same arguments has no further effect (only meaningful when not read-only)false
openWorldHintmay interact with external entities, like a web searchtrue

The defaults lean towards caution: a tool that says nothing counts as a write tool that may destroy data and reach the outside world.

The schema is blunt about trust: annotations "are not guaranteed to provide a faithful description of tool behavior", and the tools page adds that clients "MUST consider tool annotations to be untrusted unless they come from trusted servers". A hint helps an honest server explain itself. It does not stop a dishonest one.

Example ​

json
{ "name": "delete_branch",
  "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false } }

A client can ask a person before this call and skip the question for a readOnlyHint: true tool such as list_branches.

Common confusion ​

Annotations are not permissions. A server that marks drop_table as read-only has not made it read-only; only your own policy, scoped credentials and review can do that. A server can also change its hints after you trusted them, a form of rug pullRug pull: An attack in which an MCP server changes a tool's definition after people reviewed and approved it, so a tool trusted as harmless becomes harmful without a new review..

In L2M ​

L2M keeps the hints from tools/list, shows them as chips and lets tool policy match on them, reading missing hints with the spec's defaults. An admin's read-only or write mark on a registered server's tool replaces readOnlyHint (read-only classification).

Further reading ​

This website (not the L2M product) uses Google Analytics, only after you accept cookies. Cookie settings