---
title: "Report bad arguments as tool results · Agent Wranglers"
url: https://agentwranglers.se/playbook/agents-as-users/mcp-servers/tool-errors-as-results
id: AGT-16
level: Recommended
updated: 2026-10-22
tokens: 802
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Report bad arguments as tool results instead of protocol errors

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [MCP servers](https://agentwranglers.se/playbook/agents-as-users/mcp-servers.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: AGT-16
- Level: Recommended
- Chapter: [MCP servers](https://agentwranglers.se/playbook/agents-as-users/mcp-servers.md)
- Rule: Return bad arguments, missing records and business rule failures as a tool result with `isError: true`. Keep JSON-RPC errors for unknown tools, malformed requests and server faults.
- 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`.
- How: 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](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/tool-errors-for-models.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
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

```python
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()}."}]}
```

## Sources

- [MCP specification on tools (error handling)](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)

## Related rules

- AIF-16 [Return errors the model can act on](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/tool-errors-for-models.md) in AI features

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/agents-as-users/mcp-servers/tool-errors-as-results">Agent Wranglers agents as users playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Keep the tool list within a token budget](https://agentwranglers.se/playbook/agents-as-users/mcp-servers/tool-list-budget.md)
- Next: [Send cache hints and a stable order with every list](https://agentwranglers.se/playbook/agents-as-users/mcp-servers/list-cache-hints.md)
- [MCP servers](https://agentwranglers.se/playbook/agents-as-users/mcp-servers.md)