Schema depth and size stay within common validator bounds
Clients SHOULD bound schema depth and size to protect their validators, so a very deep or very large tool schema may be refused; keep depth to about 10 and subschemas well under 500.
Check spec-composition-bounds · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0
What fails
Clients are told to cap schema depth and subschema count, so a very deep or very large schema risks being refused. The thresholds used here (depth over 10, more than 500 subschemas) are IsoKron's, since the specification sets no numbers.
The rule
Implementations SHOULD apply reasonable bounds, such as a maximum schema depth, a cap on the total number of subschemas, or a per-validation time budget, to prevent a malicious schema from acting as a Denial-of-Service vector against the validator.
Source: MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons)
How to fix it
Flatten nested composition, move repeated parts into $defs, or split the tool.
- Move repeated parts into $defs and reference them.
- Flatten nested oneOf/anyOf trees; split a tool that handles many shapes into several tools.
- Drop optional deep structures the model rarely fills.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'update_issue_fields',
{
title: 'Update issue fields',
description: 'Change named fields of one issue. Use when the user asks to edit an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
title: z.string().optional().describe('New title'),
state: z.enum(['open', 'closed']).optional().describe('New state'),
}),
annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
},
async ({ issue_id, title, state }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated, Literal
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Update issue fields",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=False),
)
def update_issue_fields(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
title: Annotated[str | None, Field(description="New title")] = None,
state: Annotated[Literal["open", "closed"] | None, Field(description="New state")] = None,
) -> str:
"""Change named fields of one issue. Use when the user asks to edit 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
What are the exact limits?
The specification sets no numbers. The checker flags depth over 10 or more than 500 subschemas, which is IsoKron’s threshold for "risk of refusal", not a protocol rule.
Does schema size cost tokens?
Yes. Every tool schema is sent to the model on each request, so a large schema also shrinks the room left for the conversation.
Related checks
- No $ref to a network or external URI
- Composition branches carry presence rules, not types
- inputSchema and outputSchema are valid JSON Schema
- All checks in MCP tool input and output schemas
Further reading
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) 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