Skip to content
BENIBIX Learn

MCP Tool Annotations

AI🔌 MCPServer Features

Also known as Tool Annotations, readOnlyHint, destructiveHint, idempotentHint, openWorldHint, MCP Tool Hints

Hints on an MCP tool that say if it only reads, or may delete things.

Think of it like

It is like a label on a box that says glass. It helps, but the label could be wrong.

Example

A search tool is marked read only, so the app runs it without asking. A delete tool is marked destructive, so the app asks you first.

Why it matters

They let an app skip the questions for safe tools and slow down for risky ones. That makes tools both quicker and safer.

Definition

MCP tool annotations are hints a server attaches to a tool to say how it acts. readOnlyHint says the tool only reads and changes nothing. destructiveHint says it may delete or overwrite things. idempotentHint says calling it twice does no more than once. openWorldHint says it reaches the outside world, like the web. A client may use them to decide when to ask you first.

Example code

json
"annotations": {
  "readOnlyHint": false,
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false
}
A tool that changes things and may delete them, but stays inside its own system.
The hints come with the tool, before it is ever used.

Common mistake

Trusting them from any server. The spec says to treat them as untrusted unless the server is trusted.

Key takeaways

  1. 1
    Hints, not promises. A server could get them wrong.
  2. 2
    Safe by default. No hint means may destroy.
  3. 3
    Help the ask. Apps use them to ask or not.