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
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;
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.
- List the tools and look at the raw annotations object: every key should be one of readOnlyHint, destructiveHint, idempotentHint, openWorldHint or title.
- Rename snake_case keys to the camelCase names.
- 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.
"annotations": { "destructive_hint": true, "read_only_hint": false }"annotations": { "destructiveHint": true, "readOnlyHint": false }TypeScript SDK
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
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"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 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
- readOnlyHint, destructiveHint and openWorldHint are explicit booleans
- Tool fields have the types the schema defines
- All checks in MCP tool annotations
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP schema.ts, revision 2026-07-28 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