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.
Check annot-write-marked-readonly · Annotations (both directories) · default severity: attention · rubric 2.1.0
What fails
The name reads as a create, update or delete, but the tool sets readOnlyHint: true, so Claude would run it without asking. Reviewers check that hints match behavior; MWS-ANN-1 tests it against a live server.
The rule
readOnlyHint: Use true for retrieval, computation, or previews that do not modify the environment.
How to fix it
Set "readOnlyHint": false and an explicit destructiveHint, unless the tool only previews.
- Set readOnlyHint: false on create_, update_, set_, add_, send_ and delete_ tools.
- Choose destructiveHint for what the write does.
- If the tool really only previews, rename it (preview_update) so name and hint agree.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'update_issue_title',
{
title: 'Update issue title',
description: 'Change the title of one issue. Use when the user asks to rename an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
new_title: z.string().describe('New title, one line'),
}),
annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
},
async ({ issue_id, new_title }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Update issue title",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=False),
)
def update_issue_title(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
new_title: Annotated[str, Field(description="New title, one line")],
) -> str:
"""Change the title of one issue. Use when the user asks to rename an issue."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Why would a write be marked read-only?
Often to avoid confirmation prompts. Reviewers check annotations against behavior, and a wrong readOnlyHint is a common rejection.
Is an update destructive?
An update overwrites the previous value, which OpenAI lists as destructive. Mark it destructiveHint: true unless it only adds.
Related checks
- Deleting tools are not marked non-destructive
- Tools that start jobs or queue work are not read-only
- Every tool carries the applicable hint
- All checks in MCP tool annotations
Further reading
How this check is graded
It counts toward: Anthropic connector directory, OpenAI plugin directory. See the rubric.
Last verified against OpenAI plugin guidelines, section 6.3 on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere