MCP Tool Schemas: Validation Patterns That Reduce Agent Retries

An MCP tool schema should describe the arguments a tool needs while helping an agent produce a valid call. The best schema is not merely strict; it is explicit, unsurprising, compatible with the model’s likely output, and paired with an error that explains how to recover.

Schema correctness is not the same as agent usability

A schema can be valid JSON Schema and still create repeated failures. Models often infer argument shapes from names, descriptions, examples, and surrounding context. If the schema expects an array while ordinary user intent produces one value, the server should either accept a safe coercion or return a precise correction.

A practical schema review

• Use one clear type for each field unless multiple shapes are deliberately supported.
• Mark only genuinely required fields as required.
• Give fields descriptions that explain meaning, format, and constraints.
• Use examples for identifiers, dates, enums, and nested objects.
• Avoid overlapping tools that accept nearly identical arguments.
• Keep destructive actions separate from read-only actions.

Common mismatch: string versus array

A send-email tool may expect a list of recipients while a model produces one string for a one-recipient request. If the intent is unambiguous and coercion is safe, normalize the value before validation or clearly accept both shapes. If accepting both could hide a mistake, reject it with a correction that names the field and expected shape.

Make validation errors useful to the agent

An error should name the field, expected shape, received shape, and next action. “Invalid input” forces another guess. “The recipient field must be an array of email strings; received one string. Wrap the address in an array and retry” gives the agent a path to recovery.

Compatibility-friendly changes

• Adding an optional field is usually safer than making a field newly required.
• Keep old enum values during a deprecation window when clients may cache schemas.
• Version or alias a tool before changing the meaning of an existing argument.
• Record catalog and schema versions so failures can be tied to a deployment.
• Test the same intent across the clients and models you actually support.

Measure whether a schema change worked

Record the schema version, deployment time, affected tool, client, success rate, validation errors, retries, and workflow completion before and after the change. A rise in call volume is not enough; the change should reduce invalid calls or improve completion without increasing harmful actions.

A small regression fixture

Create cases for one value, many values, missing required input, an invalid enum, and a malformed identifier. Assert the expected validation result, recovery behavior, and tool outcome for each case. Keep the fixture versioned with the server.

Frequently asked questions