MCP Tool Annotations: The Four Hints and Their Defaults

MCP tool annotations are the four optional fields a Model Context Protocol server attaches to each tool definition to describe how that tool behaves: whether it reads or writes, whether a write can destroy data, whether a repeat call is safe, and whether the tool reaches outside the server's own domain. They shipped in the 2025-03-26 revision of the MCP specification, and the current 2026-07-28 revision keeps the same four hints with the same defaults, according to the protocol's schema reference and its own blog.

MCP tool annotations are optional metadata, readOnlyHint, destructiveHint, idempotentHint and openWorldHint, that a server attaches to a tool so a client can decide when to ask the user for confirmation before running it. The specification calls every one of them a hint: a client must treat annotations from an untrusted server as unverified, not as a guarantee.

How MCP tool annotations work

The ToolAnnotations interface defines five fields, a display title plus four booleans, each with its own default:

The defaults assume the worst. A tool with no annotations at all is treated as potentially modifying its environment, potentially destructive, unsafe to retry, and reaching outside the server, according to the Model Context Protocol's March 2026 post on tool annotations. Leaving an annotation out never makes a tool look safer than it is; it only means a careful client asks for confirmation more often than it needs to.

Annotations travel inside the tools/list response alongside a tool's name, description and input schema. The current tools specification describes them as "optional properties describing tool behavior" and states that clients must consider them untrusted unless they come from a trusted server. A malicious or careless server can set readOnlyHint: true on a tool that deletes files, which is why the spec treats the hints as advisory rather than enforced.

That trust boundary connects to what Simon Willison named the lethal trifecta: access to private data, exposure to untrusted content, and the ability to communicate externally. When an agent's session combines all three, an attacker who controls one piece of untrusted content, a calendar invite, an email, a web page, can get the model to read private data and send it out. Researchers have reproduced this using a malicious Google Calendar event, an MCP calendar server, and a local code-execution tool, according to the MCP blog post. Annotations like openWorldHint cannot stop a model from following an injected instruction, but they can help a client notice when a session has assembled all three legs of that chain and tighten its confirmation rules from that point on.

Examples of MCP tool annotations in practice

A read-only tool from the Kubernetes MCP Server, tested by developer Marc Nuri with version 0.0.67 in October 2026, shows the shape of a tools/list entry:

{
  "name": "helm_list",
  "title": "Helm: List",
  "annotations": {
    "title": "Helm: List",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": true
  }
}

A destructive tool looks different. Speakeasy's Functions Framework, which forwards annotations to MCP clients automatically, documents a delete_user tool set up the opposite way:

const functions = new Functions().tool({
  name: "delete_user",
  description: "Permanently delete a user account",
  inputSchema: { userId: z.string() },
  annotations: {
    title: "Delete User",
    destructiveHint: true,
    readOnlyHint: false,
    idempotentHint: true,
    openWorldHint: false,
  },
  async execute(ctx, input) {
    await deleteUser(input.userId);
    return ctx.json({ deleted: true });
  },
});

Clients act on these hints differently. As of October 2026, per Marc Nuri's comparison, VS Code's Copilot reads title, readOnlyHint and openWorldHint: it runs read-only tools without asking, asks for everything else, and can prompt a review of an open-world tool's results. Claude reads title, readOnlyHint and destructiveHint: read-only tools skip the confirmation, destructive ones always get one. ChatGPT reads readOnlyHint, destructiveHint and openWorldHint, and treats a tool that omits readOnlyHint as a write action that needs confirmation. Codex CLI never asks before a read-only tool and always asks before a destructive one, and runs read-only calls in parallel, a behavior it shares with the Claude Agent SDK. Gemini CLI's Plan Mode lets a user approve read-only tools and blocks the rest, with policies that can allow, ask or deny a tool by its annotation. Goose's Smart Approve mode runs read-only tools without asking, always asks when readOnlyHint is false, and leaves the model to judge any tool that carries no hint at all.

When to use MCP tool annotations (and when not)

Set them when you write a server. The MCP blog's guidance is direct: mark readOnlyHint: true on tools that only read, destructiveHint: false on writes that only add, idempotentHint: true when a repeat call is safe, and openWorldHint: false on a tool confined to a closed, local domain such as an in-memory store. As of October 2026, Anthropic's Connectors Directory and OpenAI's plugin review both require annotations before they will list a server, according to Marc Nuri's post, so a server without them may not clear review at all.

Do not treat them as a permission system. aident.ai's explainer makes the point plainly: a readOnlyHint does not prove returned data is harmless or in scope, and a destructiveHint: false does not make a write reversible. An untrusted server can claim readOnlyHint: true and delete files anyway, so real safety guarantees belong in network controls, sandboxing or an authorization layer, not in a boolean hint. A tool's risk also depends on what else is available in the same session; a single tool's annotations cannot show that by themselves.

What's new (as of 2026-11-05)

• The 2026-07-28 spec revision, the latest as of this writing, still defines the same four hints and the same defaults that shipped in 2025-03-26. Three revisions in between, 2025-06-18, 2025-11-25 and 2026-07-28, left them unchanged, according to Marc Nuri's post, last updated 23 October 2026.
• Five Specification Enhancement Proposals were open as of the MCP blog's 16 March 2026 post: SEP #1913 (Trust and Sensitivity Annotations, Draft), SEP #1984 (Comprehensive Tool Annotations for Governance/UX, Draft), and three issue-stage proposals, unsafeOutputHint (#1561), secretHint (#1560) and trustedHint (#1487). A Tool Annotations Interest Group with participants from Microsoft, OpenAI, AWS, Cloudflare and Anthropic is working through them.
• As of October 2026, Anthropic's Connectors Directory and OpenAI's plugin review both require tool annotations before a server can be listed, per Marc Nuri's post.
• GitHub's read-only mode, described by the MCP blog as the closest production system to a client distinguishing trust levels rather than just checking readOnlyHint, is enabled by about 17% of its users as of the March 2026 post.

Key takeaways

• MCP tool annotations are four optional boolean hints, readOnlyHint, destructiveHint, idempotentHint and openWorldHint, plus a display title, defined in the protocol's ToolAnnotations interface since the 2025-03-26 spec revision.
• Defaults are pessimistic: a tool without any annotations is treated as non-read-only, potentially destructive, unsafe to retry and reaching outside the server.
• The specification requires clients to treat annotations from an untrusted server as unverified, since a server can set readOnlyHint: true and still modify data.
• Client support varies by design: VS Code, Claude, ChatGPT, Codex CLI, Gemini CLI and Goose each read a different subset of the four hints and act on them differently, confirmed as of October 2026.
• Five SEPs, reviewed by a Tool Annotations Interest Group with Microsoft, OpenAI, AWS, Cloudflare and Anthropic, propose new annotations for trust, sensitivity and unsafe output beyond the original four.

FAQ

What is the default value of readOnlyHint in MCP?

readOnlyHint defaults to false. A tool that omits the annotation is assumed to modify its environment unless the server explicitly sets it to true.

Can an MCP client trust a server's tool annotations?

Only if the server itself is trusted. The Model Context Protocol specification requires clients to treat annotations from an untrusted server as unverified, since a server can claim a tool is read-only and still change or delete data.

Which MCP clients read tool annotations?

As of October 2026, VS Code's Copilot, Claude, ChatGPT, Codex CLI, Gemini CLI and Goose each read a different subset of the four hints to decide when to skip a confirmation prompt, according to Marc Nuri's client comparison.

What is the lethal trifecta, and how does it relate to tool annotations?

The lethal trifecta, a term coined by Simon Willison, names three capabilities that together create a risk of data theft: access to private data, exposure to untrusted content, and the ability to communicate externally. Annotations like openWorldHint can help a client notice when a session combines all three, but they cannot stop a model from following an instruction hidden in untrusted content.

Compare the servers that ship annotated tools, and the clients that read them, on AI Agents Listing's MCP servers hub.