MCP Tool Schema Fails in One Client

Different MCP clients can accept different subsets of a tool's schema or expose different capabilities. First compare the same server version, identity, transport and input. Otherwise the apparent client difference may actually be a configuration difference.

Save the advertised contract

Capture the tool definition returned during discovery. Include its name, input schema and any output schema. Compare it with the definition the failing client says it received.

The Inspector CLI documentation distinguishes valid schemas from portability problems. A schema can be valid JSON Schema while still conflicting with a particular client's supported behavior.

Treat the installed Inspector and SDK versions as part of the test record. Do not copy a command option from a newer release without checking availability.

Reduce the failure

Create a minimal test tool in a development environment with one string input and a plain result. If both clients handle it, add the original fields back one at a time.

Investigate required fields, nullable values, nested objects, unions and output shape. Also check whether a wrapper altered field names or serialized structured content as an unexpected type.

Comparison	What it rules out
Same account and endpoint	Different authorization
Same literal arguments	Model choosing different inputs
Minimal schema works	Basic transport failure
Full schema rejected before execution	Tool implementation failure

This is a proposed diagnostic sequence, not a guarantee that every client supports the minimal tool.

Distinguish input from output errors

If the handler never starts, inspect argument validation and protocol logs. If it runs but the client rejects the result, inspect the returned envelope and output schema.

An upstream Java SDK issue reports misleading input/output wording in an error. Read the actual failing path rather than assuming every message perfectly identifies the stage.

Do not disable validation as the permanent fix. That can turn a visible contract error into a harder-to-debug application failure.

Make the contract explicit

Use field descriptions that explain units and allowed values. State whether an omitted value differs from null. Return consistent result types across success and failure paths.

When simplifying a schema for compatibility, preserve its intended constraints in the implementation. An overly permissive schema that accepts every value may make discovery succeed while allowing invalid requests through.

Verify the user task

Retest the literal call in both clients, then test natural-language selection separately. Save a failing payload and a successful one in the regression suite.

The MCP overview explains the shared protocol. Use the server selection guide when choosing an integration, and this diagnostic when you need it to work across clients.

Related troubleshooting

• Valid AI JSON Can Still Be Wrong
• MCP Connected but No Tools: What to Check

This guide draws on the linked documentation. Examples are illustrative unless explicitly identified as measured results.