MCP Tool Input and Output Schemas
The 2026-07-28 specification lifts MCP tool schemas to full JSON Schema 2020-12 support. Input schemas still use an object root, but can use richer constructs such as oneOf, anyOf, allOf, conditionals, $ref, and $defs.
Why schema quality matters
The schema is both a validation contract and part of the model's interface. Clear field names, tight enums, correct required fields, and useful descriptions reduce invalid calls.
{
"type":"object",
"properties":{
"environment":{"type":"string","enum":["staging","production"]},
"version":{"type":"string"}
},
"required":["environment","version"],
"additionalProperties":false
}Output schemas
Structured outputs make downstream reasoning more reliable. If a tool returns a deployment result, define fields such as status, deployment ID, and URL rather than only returning prose.
Avoid schema cleverness for its own sake
JSON Schema can model complex unions and conditional branches, but models perform better when the interface remains conceptually simple. Use advanced schema features when they encode real domain rules, not to compress multiple unrelated operations into one tool.