Retain embedded JSON Schema keywords

Embedded Tool schemas can contain keywords beyond the fields MCP lists. A tool must preserve them through the operations covered by the specification instead of discarding unrecognized keywords. This is a tooling guarantee, so a valid custom keyword does not itself produce a document diagnostic.

Requirement

Tool inputSchema and outputSchema are JSON Schema objects; keywords beyond those MCP lists are permitted and preserved, and acquire MCP semantics only where a protocol version defines them.

Details

Rule ID: mcp.tool.schema-keywords.preserve
Owner: mcp
Surface: Tool · Path: inputSchema, outputSchema
Kind: preservation
Requirement level: Not specified in the rule record
Status: arbitrated · Enforcement: internal

Protocol version applicability

2024-11-05	2025-03-26	2025-06-18	2025-11-25	2026-07-28
applies	applies	applies	applies	applies

Required by

• MCP Description 0.9.0, Section 9.2
  • 9. Tools: req-tool-schema-vocabulary
  • 9. Tools: req-tool-schema-keywords-preserved

Based on

• Tier 1 — MCP schema.ts and normative specification text: MCP 2024-11-05 to 2025-11-25 schema.ts, interface Tool, inputSchema and outputSchema doc comments (“A JSON Schema object”)
  • validation/mcp-schemas/2024-11-05/schema.ts#L696-L703
  • validation/mcp-schemas/2025-03-26/schema.ts#L797-L804
  • validation/mcp-schemas/2025-06-18/schema.ts#L938-L945
  • validation/mcp-schemas/2025-11-25/schema.ts#L1257-L1265
  • validation/mcp-schemas/2025-06-18/schema.ts#L947-L955
  • validation/mcp-schemas/2025-11-25/schema.ts#L1272-L1284
• Tier 1 — MCP schema.ts and normative specification text: MCP 2026-07-28 schema.ts, interface Tool, inputSchema and outputSchema (index signature [key: string]: unknown)
  • validation/mcp-schemas/2026-07-28/schema.ts#L1981-L1997
  • validation/mcp-schemas/2026-07-28/schema.ts#L1999-L2005

Gaps and arbitrations

Arbitration: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25

Conflict: The TypeScript type of inputSchema (and outputSchema from 2025-06-18) lists only type, properties, required, and from 2025-11-25 $schema, with no index signature, while its doc comment defines the value as a JSON Schema object.

Authority: MCP schema.ts doc comment, consistent with MCP 2026-07-28

Behavior: Accept and preserve any JSON Schema keyword in these protocol versions.

Rationale: A JSON Schema object admits any keyword. MCP 2026-07-28 makes this explicit with an index signature, and rejecting keywords such as $defs or $ref would reject Tools that MCP clients accept.

Review trigger: An upstream clarification or erratum for the earlier protocol versions..

Examples

View succeeds

Source: view-fixtures/view-tool-schema-keywords-2025-11-25.json · Selected: /expected

"expected/view-tool-schema-keywords-2025-11-25.json"

Rule Source Code

tool.yaml at immutable tag v0.9.0-rc.3.