Tool Output Design

Every byte a tool returns is paid for in context tokens and in the agent's attention. The result is not a data dump; it is the next prompt the agent reads. Design it as one.

Procedure

1. List what the agent needs to decide its next step. Only those fields are essential. Everything else is optional detail or a follow-up call.
2. Define a flat, named shape for the result and keep it identical across calls.
3. Decide the size policy: default summary, expansion flags, cursor pagination, truncation limits, and references for blobs.
4. Add navigation: hasMore and cursor, GUI URLs, and a next-action hint.
5. Handle mixed outcomes with per-item status for anything that touches more than one item.

Rules with examples

Shape the response (Response Shaper)