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.
Check spec-field-types · MCP specification 2026-07-28 · default severity: blocking · rubric 2.1.0
What fails
schema.ts defines the type of every tool field: name, title and description are strings, annotations is an object of boolean hints plus a string title, outputSchema and _meta are objects, icons is an array. A string "true" is not a boolean, and clients that check types drop or misread the field.
The rule
readOnlyHint?: boolean;
How to fix it
Use the type named in the message, for example "readOnlyHint": true, not "readOnlyHint": "true".
- Use JSON booleans for hints: true and false without quotes.
- Check fields built from config files or environment variables, which arrive as strings.
- Let the SDK types catch this: ToolAnnotations in both SDKs only accepts booleans.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'close_issue',
{
title: 'Close issue',
description: 'Close one issue. Use when the user says an issue is done or resolved.',
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="Close issue",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=True, openWorldHint=False),
)
def close_issue(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
) -> str:
"""Close one issue. Use when the user says an issue is done or resolved."""
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
Would a client not read "true" as true?
Some coerce it, many do not. A client that checks types drops the field, and then defaults apply: destructiveHint defaults to true, readOnlyHint to false.
Where are the field types defined?
In schema.ts of the specification revision, which the JSON schema of the protocol is generated from.
Related checks
- readOnlyHint, destructiveHint and openWorldHint are explicit booleans
- Every tool carries the applicable hint
- Every list entry is a tool object with a name
- All checks in MCP specification 2026-07-28: tools/list rules
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