# 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. Last verified against OpenAI plugin guidelines, section 6.3 on 2026-11-18.

## 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.

Source: [OpenAI plugin guidelines, section 6.3](https://developers.openai.com/plugins/plugin-guidelines)

## How to fix it

Set "readOnlyHint": false and an explicit destructiveHint, unless the tool only previews.

1. Set readOnlyHint: false on create_, update_, set_, add_, send_ and delete_ tools.
2. Choose destructiveHint for what the write does.
3. If the tool really only previews, rename it (preview_update) so name and hint agree.

### TypeScript SDK

```ts
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

```python
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"
```

## 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](https://isokron.ai/mcp-check/checks/annot-delete-marked-safe)
- [Tools that start jobs or queue work are not read-only](https://isokron.ai/mcp-check/checks/openai-readonly-starts-job)
- [Every tool carries the applicable hint](https://isokron.ai/mcp-check/checks/anthropic-hint)
- [MCP tool annotations](https://isokron.ai/mcp-check/checks/annotations)

## Further reading

- [MWS-ANN: testing that hints match behavior](https://isokron.ai/mws#mws-ann-1)

Counts toward: Anthropic connector directory, OpenAI plugin directory.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
