MCP Tool Annotations: Read-Only, Destructive and Idempotent Hints

MCP tool annotations are optional hints a server attaches to a tool to describe its behavior. They say whether the tool only reads data, whether it might delete or overwrite something, whether repeating a call is safe, and whether it reaches the outside world. Clients use them to decide how carefully to treat a call.

Status in the 2026-07-28 spec: core (optional field). Annotations are defined in the ToolAnnotations type of the 2026-07-28 schema, unchanged in shape since they were added in 2025-03-26.

The most important rule is short. Annotations are hints, not guarantees. A client should never make a trust decision based on annotations from a server it does not trust.

What tool annotations are

Annotations live in the annotations field of a tool definition. Here is what each one means, with the defaults from the 2026-07-28 schema:

The schema gives a clear example for the last hint. A web search tool has an open world. A memory tool does not.

Display names follow a fixed order. The schema says the precedence is title, then annotations.title, then name.

Why annotations exist

A client needs to know which tool calls deserve a pause. Reading a calendar is low risk. Deleting a customer record is not. Without hints, a client has to treat every call the same, which means either asking the user about everything or about nothing.

The 2025-03-26 changelog added "comprehensive tool annotations for better describing tool behavior, like whether it is read-only or destructive." The aim is better user experience: fewer pointless prompts for safe reads, and clearer warnings for risky writes.

How it works

A server adds the hints to its tool definition. This example is illustrative, built on the field names in the spec:

{
  "name": "delete_invoice",
  "title": "Delete Invoice",
  "description": "Permanently delete a draft invoice by ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "invoice_id": { "type": "string" }
    },
    "required": ["invoice_id"]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}

Deleting the same invoice twice has no extra effect, so it is idempotent. It is destructive because the data is gone. It is closed-world because it only touches the server's own system.

A client might then show a stronger confirmation for this tool than for a read-only list_invoices. The spec does not dictate a specific UI. It does say apps SHOULD present confirmation prompts for operations so a human stays in the loop, per the Tools page.

The trust rule

The Tools page carries this warning: "clients MUST consider tool annotations to be untrusted unless they come from trusted servers." The schema repeats it: "Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers."

Why so strict? A malicious server can mark a destructive tool as read-only. If a client skipped confirmation because of that label, the server would get a free pass. Our guide to MCP tool poisoning covers how attackers abuse tool metadata.

In practice, treat annotations as a way to add caution, not remove it. A "destructive" hint should trigger a warning. A "read-only" hint from an unknown server should not skip one.

What changed across spec versions

Note that "annotations" also means something else in MCP. Content blocks and resources have their own annotations: audience, priority and lastModified. Those describe content, not tool behavior. Don't mix them up.

Common mistakes

1. Leaving defaults on a read-only tool. If you omit readOnlyHint, clients assume the tool writes and may be destructive. Set it to true for pure reads so users are not over-prompted.
2. Setting destructiveHint on a read-only tool. It only has meaning when readOnlyHint is false.
3. Using annotations as access control. They do nothing on the server. Enforce permissions in your code and your OAuth scopes.
4. Trusting hints from unknown servers. That breaks a MUST rule in the spec.
5. Mislabeling to reduce prompts. A wrong "read-only" label can lead users to approve calls they would have refused. It also erodes trust in your server.

If your team approves tool calls all day, annotations are one lever against approval fatigue. Our Learn MCP lesson on permissions and approvals shows where users see them.

Next step

Annotations describe what a tool does. Structured output describes what it returns. Read structured tool output in MCP next, or see all topics in the MCP specification reference.

Frequently asked questions