MCP missing_tool_argument vs invalid_tool_argument: three look-alikes

Three Sume MCP error codes differ by a letter or two, and each points at a different part of the call. Reading them correctly saves a model from rewriting a request that was nearly right. All three are tool errors on the tools/call request, so nothing ran and no spend was held.

The three codes

invalid_tool_arguments, plural, means the arguments value itself is wrong. The server read it and found something that is not an object, and the message says MCP tool arguments must be an object. Omitting arguments is fine: an absent or null value is treated as an empty object.

missing_tool_argument means a required top-level key is absent. The message reads that the tool requires the key, and the data has a missing field naming it. This is the idempotency_key or payload case.

invalid_tool_argument, singular, means a required key is present but is the wrong type. The message says the key must be an object, and the data has a path with the key. The common case is payload sent as a string of JSON, not an object.

Where they sit in the check order

The checks run from outer to inner. First the arguments must be an object. Then unknown top-level keys are refused with unsupported_tool_arguments. Then missing required keys. Then each required object is read, which can raise invalid_tool_argument. Only after that does the payload go through its own allowed-key and field rules, which have their own codes.

So if you see one of these three, you have not yet reached the payload rules. Fixing the outer shape may reveal a payload error next. That is normal, not a regression.

What a client should do

Log data.code and the one field the error names. For payload sent as a string, parse it into an object before you call, instead of asking the model to try again. Strict typed tool schemas on your side, such as a Zod object for payload, stop the last two codes at the client.