Contract review
MCP schema-description mismatches: a deterministic review guide
Compare MCP inputSchema properties with parameters explicitly documented in tool descriptions and interpret mismatches carefully.
- Published
- Reading time
- 6 minutes
Two contracts can drift
A tool description gives the model a natural-language contract while inputSchema gives the client a structural contract. If they disagree, the model may reason about fields the client cannot submit or omit fields the server expects.
Mechanical comparison should remain conservative. Count only names clearly marked as parameters—for example, backticked identifiers or explicit parameter labels—rather than treating every word as a field name.
Classify the direction of mismatch
A documented-but-undeclared parameter may indicate stale prose, a missing schema property, or an instruction that bypasses the visible contract. A declared-but-undocumented parameter matters when the description otherwise attempts to enumerate parameters; many concise descriptions legitimately leave schema details to the schema itself.
Neither mismatch proves unsafe runtime behavior. Inspect required fields, defaults, additionalProperties, nested objects, and server-side validation before deciding severity.
Keep schema and prose generated together
Use one source of truth where possible and test that examples validate against the published schema. Review metadata diffs alongside code changes, and version tool contracts when incompatible behavior changes.
At runtime, never treat schema validation as authorization. Validate the authenticated principal, target resource, and intended side effect after parsing the request.
Frequently asked questions
Must every schema field appear in the description?
No. A description can summarize behavior while the schema carries details. A missing mention is meaningful mainly when the prose explicitly documents a parameter list.
Can matching schema and prose prove implementation correctness?
No. They show consistency between two visible declarations, not what server code actually does.