# 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. Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) on 2026-11-18.

## 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)](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#composition-keyword-resource-use)

## 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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/spec-ref-remote)
- [Composition branches carry presence rules, not types](https://isokron.ai/mcp-check/checks/schema-oneof-branch-types)
- [inputSchema and outputSchema are valid JSON Schema](https://isokron.ai/mcp-check/checks/spec-schema-valid)
- [MCP tool input and output schemas](https://isokron.ai/mcp-check/checks/schema)

## Further reading

- [Why MCP tool design matters for agent reliability](https://isokron.ai/research/why-mcp-tool-design-matters)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
