Skip to content
IsoKron

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.

  1. Move repeated parts into $defs and reference them.
  2. Flatten nested oneOf/anyOf trees; split a tool that handles many shapes into several tools.
  3. Drop optional deep structures the model rarely fills.

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(
  '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

Python
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.

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