A tool that appears to be rejected may be failing at one of several different stages: the client may omit it during discovery, an SDK may transform its schema, or the server may reject its arguments before calling the handler. First compare the raw MCP tools/list response with the tools your host exposes; then trace a failing tools/call through the client and server. “Valid” is meaningful only relative to the schema and validator used at the point of failure.
First identify whether discovery or execution is failing
MCP tool discovery and tool execution are separate operations. A client requests tools/list to learn which tools are available, then invokes a selected tool through tools/call. The difference tells you where to look: if a tool is absent from the host’s list, investigate discovery or schema representation; if it is listed but a call fails, investigate argument validation or execution.
As an Amazon Associate I earn from qualifying purchases.
- Save the raw
tools/listresponse. Compare the server’s exact response with the tool list shown by the client or exposed to the model. - If the tool disappears, check client filtering, schema-conversion layers, name collisions, and transport-specific constraints. The MCP specification defines a Streamable HTTP case where an invalid
x-mcp-headerannotation requires the client to exclude that tool from the list. - If the tool is listed but fails, save the exact
tools/callname andarguments, the JSON-RPC response, server logs, and any validator message. Check whether the handler was reached.
For Streamable HTTP, the specification says clients must reject a tool definition if any x-mcp-header value violates the stated constraints; the tool is then excluded from tools/list. Clients should log a warning naming the tool and reason. See the MCP Tools specification.
Validate the schema the client actually receives
Inspect the inputSchema in the saved tools/list response, not just the object your server code generates. MCP requires inputSchema to be a valid JSON Schema object. If the schema omits $schema, the specification sets JSON Schema 2020-12 as the default. Make sure your validator uses the applicable dialect.
- Confirm
inputSchemais present, non-null, and an object. - Check that every name in
requiredis declared inproperties, and that optional fields have not been marked required by mistake. - Compare declared property types with the JSON values actually sent. Pay particular attention to nested object shapes and the difference between
integerandnumber. - For tools with no parameters, use one of the specification’s documented object-schema forms. Its recommended explicit empty-arguments form is
{"type":"object","additionalProperties":false}.
If you use x-mcp-header, check each annotation against the specification revision implemented by both client and server. Header names must be nonempty valid HTTP field-name tokens and unique without regard to case. They may annotate only statically reachable primitive integer, string, or boolean properties; number is not allowed. The specification also constrains integer values to the safe IEEE-754 range. These restrictions can make a tool disappear at discovery rather than produce a call-time validation error.
Check whether an SDK transforms the schema
A host or SDK may map an MCP schema into another tool format before presenting it to a model. That means the schema validated by your server may not be the schema the model-facing runtime sees. Capture both versions when instrumentation allows it, and note whether schema conversion is enabled.
Rank #2
For example, the OpenAI Agents SDK MCP documentation describes convert_schemas_to_strict as a best-effort conversion. It states: “If a schema cannot be converted, the original schema is used.” Do not assume conversion is the cause without checking the resulting schema and the SDK’s behavior.
Trace call-time validation at the server
When the tool is visible, test the actual call arguments against the validator configured on the server. Check required fields, null handling, number-versus-integer values, formats, and nested object structure. Keep the real error output: it can distinguish an input mismatch from a failure in the handler or elsewhere in the request path.
Server SDKs can validate before the handler runs. The MCP Java SDK documentation says tool arguments are validated against inputSchema by default; on validation failure, it returns a tool result with isError and a textual error instead of invoking the handler. Confirm whether the handler was reached before changing the schema or debugging the handler itself. The Java SDK documents that validation can be disabled, but use that only as an SDK-specific diagnostic control when appropriate—not as the first fix, since bypassing validation can conceal a contract mismatch.
Rule out failures that are not schema rejections
If discovery succeeds but execution fails or times out, check the rest of the request path before changing the schema. Microsoft’s troubleshooting guidance includes handshake and tool-list checks, authentication, protocol response format, concurrency, and parameter validation. Its steps are documented for registering MCP servers as agent connectors for Microsoft 365, so treat them as a useful checklist for that deployment rather than proof that every host behaves identically.
- Can the client reach the configured endpoint and complete the MCP handshake?
- Are credentials present, valid, and authorized for the requested operation?
- Does the server return a response in the expected protocol format?
- Can the server handle concurrent requests, and does it respond before the client’s timeout?
- Do the actual arguments satisfy the server’s schema validator?
See Microsoft’s MCP server troubleshooting guidance.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Compare deployments at the boundary that differs
When the same tool behaves differently in two environments, compare the evidence stage by stage instead of treating MCP clients as interchangeable.
| What to compare | What it can reveal |
|---|---|
Raw server tools/list schema versus the client-visible definition |
Whether the tool is omitted or altered during discovery or representation. |
| Schema dialect and SDK conversion settings | Whether the client or runtime is interpreting a transformed schema rather than the server’s original one. |
Transport and x-mcp-header annotations |
Whether Streamable HTTP discovery constraints exclude the definition. |
| Call arguments versus server validator behavior | Whether a listed tool is rejected before its handler is invoked. |
| Handshake, authentication, protocol response, concurrency, and timeout behavior | Whether an apparent schema failure is instead a connection, authorization, or execution problem. |
No prevalence figure for silently rejected MCP schemas is established by the official materials cited here. Diagnose the specific client, transport, and validator in the failing deployment rather than assuming the behavior is universal.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
