How should an agent handle tool errors and very large tool results?

Return errors to the model as tool results marked as errors, with a message that says what went wrong and what to try instead, so the agent can recover. Keep results small by default: paginate, filter and truncate large outputs, return the fields that matter rather than raw dumps, and tell the model how to get more. Handle infrastructure failures (timeouts, rate limits) in your own code with retries before the model ever sees them.

Errors

On the Claude API, a tool result can carry is_error: true. The model then knows the call failed and can try again with other arguments, choose another tool, or tell the user. Good error messages are instructions:

• Bad: Error 400
• Good: No customer found with id "C-1234". Ids look like "CUS-000123". Search by email with find_customer instead.

Sort errors into three kinds:

1. The model's mistake (bad arguments, unknown id): return a helpful error so it can fix the call.
2. Temporary failure (timeout, rate limit, 5xx): retry with backoff in your code first. Only report to the model if retries fail.
3. Not allowed (permission denied, action blocked by policy): say so clearly, so the model does not keep trying other routes to the same result.

Also cap retries: an agent that keeps calling a failing tool is a classic runaway loop.

Large results

Anthropic's guide to writing tools for agents recommends pagination, range selection, filtering and truncation with sensible defaults for anything that could be large, and notes that Claude Code limits a tool response to 25,000 tokens by default. In practice:

• Return what the agent needs, not everything the API gives you: names and ids that mean something, not internal UUIDs and fifty unused fields.
• Paginate lists and search results, and say how to fetch the next page.
• Offer a detail level: a concise default, with a parameter for the full record.
• When truncating, say so: "Showing the first 50 of 1,240 rows. Add a filter on date or status to narrow it." That steers the model to a better next call.
• Store big artefacts (a full log, a large file) and return a reference the agent can read in parts.

Why it matters

Every token a tool returns stays in the context for later turns, costing money and attention. And an agent that cannot understand an error will guess, loop or give up.

How to test it

Include failure cases in the agent's evaluation set: missing records, timeouts, permission errors, huge results. Check that the agent recovers or explains, rather than inventing an answer.