Report bad arguments as tool results instead of protocol errors

How to do it

Clients pass tool results to the model, which can fix its arguments and retry. Many clients do not pass JSON-RPC errors on, so the model sees only that the call failed. Say what was wrong and what a valid value looks like, such as "Date must be in the future. Today is 2026-10-22." Answer an unknown tool with -32602, which the 2026-07-28 revision also uses for a resource that does not exist. The message itself follows Return errors the model can act on.

Examples

JavaScript example

if (new Date(args.date) <= new Date()) {
  return { isError: true, content: [{ type: 'text', text: `date must be in the future. Today is ${new Date().toISOString().slice(0, 10)}.` }] };
}

Python example

if date.fromisoformat(args["date"]) <= date.today():
    return {"isError": True,
            "content": [{"type": "text", "text": f"date must be in the future. Today is {date.today().isoformat()}."}]}

How to check

A test calls a tool with a date in the past and gets a result with isError: true and a message naming the field. A call to a tool name that does not exist gets a JSON-RPC error with code -32602.

Sources

• MCP specification on tools (error handling)

Related rules

• AIF-16 Return errors the model can act on in AI features