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

Check `spec-annotation-key-case` · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0. Last verified against MCP schema.ts, revision 2026-07-28 on 2026-11-18.

## What fails

ToolAnnotations defines readOnlyHint, destructiveHint, idempotentHint and openWorldHint, in camelCase. A key such as destructive_hint is not one of them: clients ignore it and apply the default instead (readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true), so the hint the author meant never reaches them. The Python SDK (mcp 1.x) produces exactly this when ToolAnnotations is given snake_case arguments, because it keeps unknown fields as extras.

## The rule

> destructiveHint?: boolean;

Source: [MCP schema.ts, revision 2026-07-28](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts)

## How to fix it

Use the spec's key name, for example ToolAnnotations(destructiveHint=True) in the Python SDK, so the list carries "destructiveHint": true.

1. List the tools and look at the raw annotations object: every key should be one of readOnlyHint, destructiveHint, idempotentHint, openWorldHint or title.
2. Rename snake_case keys to the camelCase names.
3. Python: upgrade to mcp 2.x, or pass camelCase arguments to ToolAnnotations on mcp 1.x. TypeScript: write the camelCase keys; the SDK passes unknown keys through unchanged.

Before:

```json
"annotations": { "destructive_hint": true, "read_only_hint": false }
```

After:

```json
"annotations": { "destructiveHint": true, "readOnlyHint": false }
```

### 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(
  'delete_issue',
  {
    title: 'Delete issue',
    description: 'Delete one issue permanently. Use only when the user explicitly asks to delete an issue.',
    inputSchema: z.strictObject({
      issue_id: z.string().describe('Issue ID, for example ISS-42'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
  },
  async ({ issue_id }) => ({ 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="Delete issue",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=True, openWorldHint=False),
)
def delete_issue(
    issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
) -> str:
    """Delete one issue permanently. Use only when the user explicitly asks to delete an issue."""
    return "Done"
```

## Questions

### Why does my Python server list destructive_hint?

On the 1.x line of the Python SDK, ToolAnnotations(destructive_hint=True) keeps the snake_case argument as an extra field, so tools/list carries "destructive_hint": true (observed on mcp 1.30.0). mcp 2.3.0 maps snake_case arguments to the camelCase names, and the list carries "destructiveHint": true.

### Can the TypeScript SDK produce this too?

Yes. The TypeScript SDK 2.4.0 passes the annotations object through as written, so annotations: { destructive_hint: true } from plain JavaScript, a cast, or a config file reaches clients with the snake_case key.

### What happens to a tool with only snake_case hints?

Clients see no hints and apply the defaults: readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true. Every call asks for confirmation, and both directories see the hints as missing.

## Related checks

- [Every tool carries the applicable hint](https://isokron.ai/mcp-check/checks/anthropic-hint)
- [readOnlyHint, destructiveHint and openWorldHint are explicit booleans](https://isokron.ai/mcp-check/checks/openai-hints-explicit)
- [Tool fields have the types the schema defines](https://isokron.ai/mcp-check/checks/spec-field-types)
- [MCP tool annotations](https://isokron.ai/mcp-check/checks/annotations)

Counts toward: MCP specification 2026-07-28.

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

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