Chapter 2 · Practice 4 of 4
Return concise, meaningful results and actionable errors
Why it matters
What a tool returns becomes part of the agent's context, so every field costs attention and tokens.
Anthropic's tools article recommends:
- High-signal fields such as names and file types, rather than low-level ids like
uuidormime_typethe model cannot use. - A
response_formatoption, such as concise or detailed, so the agent asks for detail only when it needs it. In the article's Slack example, the concise response used about a third of the tokens of the detailed one. - Pagination, filtering and truncation with sensible defaults. The article notes that Claude Code limits tool responses to 25,000 tokens by default.
- Error messages that say how to fix the call, with an example of correct input, instead of opaque codes or stack traces.
When you truncate, tell the agent so and suggest a narrower query.
Avoid
- Returning whole database rows or raw API payloads to the model
- Errors such as "400 Bad Request" with no hint of what to change