Tool results are the biggest thing in your context
The most overlooked lever in agent engineering. What comes back from a tool is usually the majority of the context and almost nobody designs it, which is why runs get expensive and lose the thread at the same time.
TL;DR: Design what a tool returns as carefully as what it accepts. Raw API responses put irrelevant fields, unbounded lists and deep nesting into a context that is resent on every subsequent step. Shape the result to what the agent needs to decide the next action, cap its size, and hand back a reference for anything large.
Where you are. You have designed the tool surface. The return path is next, and nobody thinks of it as design. It is also, per the first lesson of module 2, usually the majority of your context and therefore the majority of your cost.
Why this is the lever
Recall the accumulation: everything is resent every step. A tool result is not paid for once. It is paid for on every step after the one that produced it.
A query returning forty rows at step two, in a run that goes to step ten, is carried through eight further calls. If those rows have twelve fields each and the agent needed two of them, you are transmitting several thousand tokens of irrelevance, repeatedly, and diluting attention on every step while doing it.
That is the whole argument for this lesson. Result design is cost control and quality control at once, and they are the same intervention.
What a raw response does wrong
Three things, and they compound.
Fields nobody needs. An order object with created timestamps, internal flags, foreign keys and audit metadata. The agent needs the status and the amount.
Unbounded lists. A search returning as many results as it found. One query can dominate the entire remaining run.
Deep nesting. Structure the agent has to traverse mentally to find the value it wants, spending attention on shape rather than substance.
Shape the result for the decision
The question to ask is not "what did the API return" but "what does the agent need in order to choose the next action?"
Usually much less. A few practical moves.
Project to the fields that matter. Return status and amount, not the object. If a later step genuinely needs more, that is a second call, made only when required.
Cap the list, and say you capped it. Return the top five and state "5 of 47 shown". The count matters: an agent that knows 47 matched behaves differently from one shown five with no context, and truncating silently is how an agent concludes a customer has five orders.
Flatten. One level where you can. Fewer tokens and less to traverse.
Summarise where the detail is not decision-relevant. A document search can return passages, or "3 relevant sections in the refund policy, most relevant: [one paragraph]".
Return a reference for anything large. This is the move people miss. A tool that produces a large artefact, a file, a full report, a long document, should return an identifier and a summary rather than the content. If a later step needs the content, a second tool fetches it. The agent decides whether to pay for it, instead of you paying on its behalf every step thereafter.
Say what happened, not just what came back
A result also carries a status, and being explicit about it prevents a recurring failure.
Empty is not the same as failed. "No orders found for that customer" and "the order service is unavailable" lead to completely different next actions, and an empty list represents both if you let it. Distinguish them.
Say when a result is partial. Truncated, timed out halfway, or filtered by permissions. An agent reasoning over a partial result as if it were complete will state a wrong conclusion confidently.
Include what would let the agent narrow the search. "47 matches, too many to be useful, try adding a date range" is a result that produces a better next call. A bare list of 47 produces a guess.
The size budget
A useful discipline: give each tool a token budget for its result and enforce it in code.
Something like a few hundred tokens for a lookup, a thousand or two for a search. When a result exceeds it, truncate deliberately and say so, rather than letting one call consume a quarter of the window.
Then measure. Log result sizes per tool, and the largest one will usually surprise you. In most agents that have not done this, a single tool is responsible for the majority of context growth.
Do this before moving on
Take one tool and print its result exactly as it enters the message list.
Count the tokens, then mark which parts the agent actually used to decide its next action. The unmarked portion is being resent on every subsequent step for nothing. Trim it, rerun the same task, and compare total tokens for the run. It is usually the largest single saving available, and it costs one afternoon.
Go deeper
- Context engineering is the discipline this lesson belongs to, generalised past tool results.
- Agent memory is what to do once trimming results is not enough, and it is module 4.
- Practice question: How do you control agent cost in production? is where result size turns out to be the dominant term.
- Practice question: How do you manage an agent's context? is the same problem stated as a memory question.
- Practice question: How does retrieval work inside an agent loop? is the case where results are passages and shaping them matters most.
Key takeaways
- A tool result is resent on every step after the one that produced it, so its cost is multiplied by the remaining run length.
- Shape results for the decision: project fields, cap lists while stating the true count, flatten, and summarise what is not decision-relevant.
- Return a reference and a summary for anything large, and let a second call fetch the content if it is needed.
- Distinguish empty from failed and mark partial results, or the agent will reason confidently over an incomplete picture.
Check yourself before an interviewer does. Answer from memory first.
A search tool returns forty results at step two of a ten-step run. What is the real cost?