MCP tool annotations
Tool annotations are four optional hints on each MCP tool (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) plus a display title; clients use them to decide when to ask the user before a call, and both directories require them.
The MCP specification makes annotations optional and untrusted: a client may use them to choose when to confirm a call, never to grant permission. The two directories go further. The Anthropic connector checklist requires a title and the applicable hint on every tool, and the OpenAI guidelines require readOnlyHint, destructiveHint and openWorldHint as explicit booleans on every tool.
Missing or wrong hints are among the most common reasons a server is sent back from review. The checks below cover each rule, with the exact wording of both platforms and the fix for each SDK.
The 10 checks
- Annotation hints use the spec’s key names: ToolAnnotations keys are camelCase (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); a snake_case key such as destructive_hint is not a hint, so clients ignore it and apply the default instead.
- Every tool has a title: Every tool needs a short human-readable title, such as "Create issue", for the Claude connector directory; either the top-level title field or annotations.title counts.
- Every tool carries the applicable hint: The Anthropic connector checklist requires every tool to carry the applicable hint: readOnlyHint: true on read-only tools and destructiveHint: true on tools that modify or delete data; Claude uses them to decide which calls run without confirmation.
- destructiveHint: false on a write: the platforms word this differently: OpenAI says destructiveHint: false is right for additive writes with no destructive or irreversible effect; Anthropic asks for destructiveHint: true on tools that modify or delete data and does not say whether a pure create counts, so false is defensible only for writes that purely add.
- readOnlyHint, destructiveHint and openWorldHint are explicit booleans: OpenAI requires readOnlyHint, destructiveHint and openWorldHint as explicit true or false booleans in every tool’s annotations, even where the MCP specification has a default; the submission form will not continue until they are set.
- Tools that start jobs or queue work are not read-only: A tool that starts a job, queues work, schedules something or persists an artifact changes external state, so OpenAI asks for readOnlyHint: false even if the tool returns only a job ID.
- Read-only tools set destructiveHint: false: A tool with readOnlyHint: true should set destructiveHint: false: the specification ignores destructiveHint on read-only tools, but the pair contradicts itself and OpenAI asks for false.
- Deleting tools are not marked non-destructive: Tools that delete, overwrite, cancel, revoke or reset must set destructiveHint: true; with false, clients run them without a confirmation prompt, and both directories treat that as incorrect annotations.
- Tools named as writes are not marked read-only: A tool whose name reads as a create, update or delete must not set readOnlyHint: true, or clients run it without asking; set readOnlyHint: false and an explicit destructiveHint unless the tool only previews.
- Tool fields have the types the schema defines: Tool fields must have the types schema.ts defines: name, title and description are strings, each annotation hint is a boolean, outputSchema and _meta are objects, icons is an array; "readOnlyHint": "true" is a string, not true.
Other topics
- Directory review rules for MCP tools
- MCP tool names
- MCP tool descriptions
- MCP tool input and output schemas
- Tool poisoning and hidden text
- Write-surface design for MCP tools
- MCP specification 2026-07-28: tools/list rules
Sources last verified on 2026-11-18. How findings become grades.
Check your tool list: paste your tools/list, nothing is sent anywhere