---
title: "Return errors the model can act on · Agent Wranglers"
url: https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/tool-errors-for-models
updated: 2026-10-20
licence: "All rights reserved"
---

# Return errors the model can act on

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Structured output and tools](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools)
- Rule: When a tool fails, return a short structured error that says what went wrong and what to try next. Never return a stack trace or an empty result.
- How: Return an object with an error code, a plain message and, where it helps, the allowed values. Mark the result as an error in the provider's format, such as `is_error: true` on an Anthropic `tool_result` block. Answer every tool call the model made, including each of several parallel calls, in the next request. A missing result makes the provider reject the request. Keep internal details, such as table names and hosts, in your own logs. Return "no results" as an explicit message, so the model does not guess.
- Check: A test calls each tool with a bad argument and with a missing record. Both results are short JSON objects with a code and a message, and neither contains a stack trace or file path. A test with two parallel tool calls, one failing, sends back two results.

Example:

```ts
if (!order) return { isError: true, content: { code: 'order_not_found', message: `No order ${orderNumber} for this customer. Ask the customer to check the number.` } };
```

```python
if order is None:
    return {"is_error": True, "content": {"code": "order_not_found",
            "message": f"No order {order_number} for this customer. Ask the customer to check the number."}}
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers ai features playbook: https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/tool-errors-for-models`.

- Previous: [Design tools like a small public API](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/tool-design)
- Next: [Make tools that change things safe to repeat](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/idempotent-tools)
- [Structured output and tools](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools)