Skip to content

What are MCP tool annotations?

Glossary entry. Checked on 19 November 2026.

Tool annotations, in plain words

Tool annotations are optional hints an MCP server attaches to each tool: whether it is read-only, destructive, idempotent or reaches the open world. Apps use them to decide what to ask you before running a tool, but they are hints, not guarantees.

The four hints

  • readOnlyHint (default false): the tool doesn't change anything.
  • destructiveHint (default true): a change may destroy rather than add.
  • idempotentHint (default false): repeating the same call is safe.
  • openWorldHint (default true): the tool reaches things outside a closed set, such as the web.

A tool without annotations is treated pessimistically: not read-only, possibly destructive, not idempotent, open-world. ChatGPT, for example, asks you to confirm every tool not marked read-only.

Not a safety guarantee

The MCP project is clear that annotations may not describe a tool faithfully, that clients should treat them as untrusted unless the server is trusted, and that hard guarantees need network controls or sandboxing. See Is this MCP server safe?

Share this definition

Lessons that use this term

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.