MCP Tool Annotations: readOnlyHint, destructiveHint, openWorldHint and title Explained
Tool annotations are optional hints in the MCP spec, but directories treat them as required. Claude requires every tool to have a title and the applicable readOnlyHint or destructiveHint, and uses them for auto-permissions. ChatGPT requires readOnlyHint, destructiveHint, and openWorldHint as explicit booleans on every tool and checks that they match behavior. Set them honestly: an annotation that says read-only on a tool that writes is a common rejection.
Annotations are a few booleans on each tool, yet they decide whether a user sees a confirmation prompt and whether a reviewer approves your server. Here is what the spec defines and how Claude and ChatGPT read them. mcplisted is not affiliated with Anthropic or OpenAI.
What the spec defines
The 2025-06-18 schema defines ToolAnnotations with these fields and defaults:
| Field | Meaning | Default if omitted |
|---|---|---|
title |
Human-readable title | none |
readOnlyHint |
Tool does not modify its environment | false |
destructiveHint |
Tool may perform destructive updates (only meaningful when not read-only) | true |
idempotentHint |
Repeated calls with the same arguments have no extra effect (only meaningful when not read-only) | false |
openWorldHint |
Tool may interact with an open world of external entities | true |
The defaults are conservative. A tool with no annotations is treated as a possibly destructive, open-world write. That is one reason to set them explicitly.
The spec also says clients MUST treat annotations as untrusted unless they come from trusted servers. Annotations are hints for the client, not security controls.
A tool can carry a title in two places: the top-level title field and annotations.title. The schema's display precedence is title, then annotations.title, then name. Setting the top-level title is the clean choice.
How Claude uses them
Anthropic's checklist says every tool must include a title and the applicable hint: readOnlyHint: true for read-only tools and destructiveHint: true for tools that modify or delete data. These "determine auto-permissions in Claude": read-only tools can run without per-call confirmation, and destructive tools always prompt.
In the developer portal, the Tools step groups your tools as read-only or write based on these annotations and flags any tool missing a title or annotation. Anthropic says to fix flagged tools on the server before submitting. See the Claude submission guide.
How ChatGPT uses them
OpenAI's plugin guidelines require readOnlyHint, destructiveHint, and openWorldHint set to explicit booleans in every tool's annotations object. Its definitions are stricter than the spec's one-liners:
- readOnlyHint:
truefor retrieval, computation, or previews.falsefor any state change, including persisting artifacts, starting jobs, queuing work, writing logs, posting messages, sending emails, or uploading files. - destructiveHint:
falsefor read-only tools. For writes,truefor deletion, overwriting, cancellation, access revocation, or irreversible sends. OpenAI says being able to undo an action does not by itself justifyfalse. - openWorldHint:
truefor public or open-ended entities, including read-only web search. A tool limited to a bounded private account or workspace may usefalse, even if the service is externally hosted.
OpenAI's tool scan imports the annotation values your server advertises, and its review FAQ lists mismatched annotations as a common rejection. A justification in the form does not override the server value: if a tool is truly read-only, change the annotation, deploy, and rescan.
On justifications, OpenAI's docs currently disagree. The guidelines say annotation justifications are no longer required; the submission errors reference still lists justification_required. Keep a one-line reason per value ready.
How Gemini CLI handles confirmation
Gemini CLI's docs describe tool confirmation based on server trust settings and user allow-lists ("proceed once," "always allow this tool," "always allow this server"). They do not describe annotations as part of that decision, so treat annotations there as informational.
Worked examples
| Tool | readOnlyHint | destructiveHint | openWorldHint |
|---|---|---|---|
search_docs (your own index) |
true |
false |
false |
web_search |
true |
false |
true |
create_draft (private workspace) |
false |
false |
false |
send_email |
false |
true |
true |
update_record (overwrites fields) |
false |
true |
false |
delete_project |
false |
true |
false |
export_report (writes a file) |
false |
false |
false |
A complete descriptor:
{
"name": "delete_project",
"title": "Delete project",
"description": "Permanently deletes a project and its tasks in the connected workspace.",
"inputSchema": {
"type": "object",
"properties": { "project_id": { "type": "string" } },
"required": ["project_id"]
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"idempotentHint": true,
"openWorldHint": false
}
}
In the TypeScript SDK the same values go in the annotations field of registerTool.
Common mistakes
- Leaving annotations off and relying on defaults (defaults mean destructive and open-world)
-
readOnlyHint: trueon a tool that writes a log entry or enqueues a job -
destructiveHint: falseon an update that overwrites data -
openWorldHint: falseon a tool that sends messages to external recipients - One tool with a
modeparameter that is sometimes read-only and sometimes destructive
The last one is better solved by splitting the tool, which Anthropic requires anyway for tools that mix safe and unsafe HTTP methods. See why MCP servers get rejected.
Annotations are not authorization
Both vendors say annotations do not replace server-side checks. OpenAI: they "do not grant permission or replace authentication, authorization and scope checks, input validation, or human confirmation for irreversible operations." Keep enforcing scopes in every handler, as covered in the security checklist.
To see every tool's annotations on your live server at once, run a free check.
Run a free check on your MCP server →Paste your URL and see what Claude, ChatGPT and Gemini reviewers will flag.
FAQ
Are tool annotations required by the MCP spec?
No. The spec makes them optional hints. Claude and ChatGPT make them required for directory listing.
What happens if I omit destructiveHint?
The spec default is true, so clients may treat the tool as destructive. ChatGPT requires an explicit value at submission.
Do I need openWorldHint for Claude?
Claude's checklist names title, readOnlyHint, and destructiveHint. Adding openWorldHint costs nothing and is required for ChatGPT.
Can I mark a tool read-only if it only writes logs?
OpenAI says no: writing logs, queuing work, or starting jobs means readOnlyHint should be false.
Sources
- MCP specification 2025-06-18: Schema reference
- MCP specification 2025-06-18: Tools
- Connector pre-submission checklist (Claude docs)
- Submit a connector to the directory (Claude docs)
- Plugin guidelines (OpenAI docs)
- Remote MCP server review requirements (OpenAI docs)
- Plugin submission errors (OpenAI docs)
- MCP servers with Gemini CLI
Rules change. If something here is out of date, email hello@mcplisted.com and we'll fix it. See our editorial policy.