Skip to content
IsoKron

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;

Source: MCP schema.ts, revision 2026-07-28

How to fix it

Use the type named in the message, for example "readOnlyHint": true, not "readOnlyHint": "true".

  1. Use JSON booleans for hints: true and false without quotes.
  2. Check fields built from config files or environment variables, which arrive as strings.
  3. Let the SDK types catch this: ToolAnnotations in both SDKs only accepts booleans.

TypeScript SDK

TypeScript
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

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="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.

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