Tool calls
tools/call returns a validation error
Fix MCP tools/call validation errors by matching generated schemas, JSON-RPC params, and Code Mode execute arguments.
Symptom
tools/list works, but tools/call returns invalid arguments, schema validation failed, or missing required parameter.
First check
Call tools/list or search_docs with schema detail and compare the tool arguments against the generated input schema.
Quick fix
Send params.name as the exact tool name and params.arguments as a JSON object with only schema-supported fields.
Validate the JSON-RPC envelope
The method should be tools/call. The params object should include name and arguments. Arguments must be an object, not a JSON string, not an array, and not nested under input unless the generated schema explicitly asks for input.
Match required parameters exactly
Generated schemas preserve required path, query, header, and body fields from the OpenAPI source. Case, enum values, and nested object names matter. Use search_docs with schema detail when you are not sure which field the agent should send.
Do not guess Code Mode execute shape
For Code Mode servers, execute expects a constrained code snippet and optional result controls. The snippet should call methods returned by search_docs. Arbitrary JavaScript, unsupported loops, or unknown client methods will fail before any upstream API call.
Look for model-added fields
Agents often add explanatory keys such as reason, query, or payload. If those keys are not in the schema and the tool is strict, remove them or ask the agent to retry with the exact schema.
FAQ
Should I relax every schema to avoid validation errors?
No. Validation errors are useful guardrails. Fix the call shape or source OpenAPI schema instead of accepting unknown fields globally.
How do I debug a missing path parameter?
Search docs for the operation, inspect schema detail, then send the path parameter as a normal argument field using the exact generated name.