Tool Result — AI Glossary

Reference details

Related terms

• Tool Use
• Tool Selection
• Assistant Message

How it works

1. After the model emits a tool call, the harness executes it and returns a tool message carrying the output and the call id that correlates it to the request.
2. The result enters the conversation as context and is re-sent on every subsequent request for the rest of the run, so its size is not a one-time cost but a recurring one.
3. Content type matters: text and JSON are read as tokens, images consume their own budget, and a result that is a large blob of structured data spends most of its tokens on syntax the model does not need.
4. Errors belong in the result, not as an exception. A tool message saying what failed and what the model might do instead lets the loop recover; a thrown exception ends the run and discards the context that would have made recovery possible.
5. The projection from raw output to returned result is a design decision that is frequently skipped. A tool returning the full API response rather than the three fields the agent uses is the single most common cause of context exhaustion.
6. Large results are handled by returning a summary plus a handle — an id, a path, a query — so the model can ask for more if it needs to rather than carrying everything in case it does.

Example: Why the result size is a recurring cost

A tool returns 50,000 tokens of raw JSON per call. Against a 200,000-token window the fourth call exhausts it: 4 x 50,000 = 200,000, with nothing left for the system prompt, the user's question or the model's reasoning — so a ten-call run is not merely expensive, it is impossible. Project the output down to the fields the agent actually uses, say 2,000 tokens, and ten results occupy 10 x 2,000 = 20,000, a tenth of the window. The recurrence is the sharper cost. A result entering the conversation at turn two is re-sent on every later turn, so across a ten-call run the first result is billed 10 times, the second 9, and so on down to 1: total input from results alone is 2,000 x (10 + 9 + ... + 1) = 2,000 x 55 = 110,000 tokens, against the 20,000 they would cost if each were paid for once. That 5.5x multiplier is the reason trimming tool output is usually the highest-leverage change available in an agent loop — it is the one saving that applies to every remaining turn at once, rather than to the turn that made the call.

Commonly confused with

A tool result is not a function return value, and the difference is that it is read rather than consumed. A function's caller is code that indexes into a known structure and ignores everything else, so returning a large object is free. A tool result's caller is a model that pays for every token, carries it for the rest of the conversation, and has to locate the relevant part by reading. The same payload that is free in a function call is the dominant cost in an agent loop, which is why tools written for programs usually need a projection layer before an agent uses them.

When to use it

Reach for it when:

• Projected to the fields the agent uses, with the raw response retained out of band if it is needed for debugging.
• Carrying errors as content, so the loop can read what failed and adjust rather than terminating.
• With a handle for large payloads — a reference the model can expand on demand instead of receiving upfront.
• With explicit emptiness: a result saying no rows matched is actionable, while an empty string reads as a malfunction.

Reach for something else when:

• Returning full API responses unprojected, which is the usual route to context exhaustion.
• Raising exceptions instead of returning an error result, which discards the context needed to recover.
• Embedding large images or binaries where a reference would do, since they consume budget on every subsequent turn.
• Truncating mid-structure to fit. Half a JSON object is worse than a summary, because the model will reason over the fragment as if it were complete.

Continue your research

Use these connected ModelRefs sections to compare alternatives, inspect implementation paths, and review the evidence and governance boundaries relevant to Tool Result — AI Glossary.

• Browse models
• Review providers
• Inspect benchmarks
• Explore workflows
• Learn AI concepts
• Read decision guides
• Review trust and methodology
• Start a decision path