Module 3 · Agent Tools, Knowledge, Memory & Research Design · scripted
What Comes Back: Designing Tool Results
Overview
A tool call is the agent speaking to the computer; the result is the computer speaking back — and here is the fact this lesson stands on: a tool result is a message in the conversation. The moment it returns, it is context — conditioning every turn that follows, re-read and re- billed by the recurrence forever. So the result deserves the same design attention as the name and the grammar. In this lesson: the dump that floods the context, and the ladder of designs — truncate with a handle, let the agent search, let the agent ask — that puts just enough into the conversation and leaves an address for the rest.
Where this fits
Every time an agent goes and gets information, the getting ends in a tool result — a message landing in the conversation. The shape of that message decides how useful the information is once it arrives. This lesson is about doing the getting well: just enough in the result, with an address for the rest.
Where this fits
The other half of the tool
We pour attention into the naming of a tool, its description, its parameters, its implementation. But equally powerful — and almost always an afterthought — is the other half: what comes back. How the result of using a tool is represented to the agent shapes everything that happens next.
Start from the key fact, which you already know:
The key fact
A tool result is a user message. The moment it returns, it is part of the conversation — part of the context — conditioning every turn that follows, and billed by the recurrence on every iteration after.
Results let the agent look up its own context
The simplest thing a result can do is provide information: read this file — here are the contents. This is the real power of tool results: the agent can look up the context it needs for itself. It decides what it needs, goes and gets it, and reads it — we just have to give it the tools.
But there is a problem hiding in that simplicity. Watch what happens when the tool returns everything it has — far more context than the next decision needs:
You have the following tools available for use:
- read_document( name )
Task: What are the rules for night deliveries at the harbor?
read_document(name = "harbor-regulations.pdf")[187 pages: definitions, port authority structure, vessel classes,
mooring fees, environmental provisions, appendices A–J …]So we don't naively dump. Below are the standard patterns — and notice that they form a ladder, each fixing the one before it.
Pattern 1 · Truncate — but return a handle
The most basic move: cap the result. First 1,000 characters, a summary line, a row limit. But whatever we cut may be exactly what the agent needs — so never truncate without returning a handle to what was left out:
read_document(name = "harbor-regulations.pdf")[doc-77 · 187 pages · showing page 1 of 187]
"Chapter 1: Definitions. In these regulations, 'vessel' means…"
→ read_pages(doc, from, to) is available for the remainder.read_pages(doc = "doc-77", from = 2, to = 3)[pages 2–3: more definitions …]Pattern 2 · Let the agent search
Instead of scanning, give the agent a text search — a grep. Now the agent pulls in context on its own: it decides what it needs, searches for it, and reads only that. We cannot enumerate everything it might need to find, so the search pattern is the agent's to write:
search_document(doc = "doc-77", pattern = "night deliver")0 matches.search_document(doc = "doc-77", pattern = "night")2 matches: p. 12 "overnight mooring"; p. 98 "night watch staffing".Pattern 3 · Let the agent ask
The strongest standard pattern: let the agent ask. Asking is a tool built around a prompt. Behind the tool, the question and the document are placed into a fresh prompt to another LLM, and its answer comes back as the result:
ask_document(doc = "doc-77", question = "What rules govern deliveries
at night? Include exact section numbers and any defined terms.")Relevant provisions: §142 "Deliveries outside ordinary working hours
(23:00–06:00)" — permitted only at Quay 3, max sound level 55 dB,
advance notice to the port authority by 16:00. Defined term: 'quiet
period' (§8). Excerpts: "…deliveries during the quiet period shall
use the eastern access road…"The retrieval ladder
(There are more sophisticated techniques — they come later — but these three cover most of what agents need.)
A well-designed result returns just the right amount of context
Every result design is aiming at the same narrow target:
Too little · too much · just enough
That last line is the design question to ask of every tool you build: what does the agent need in its context to make its next decision — and what can stay behind a handle?
Results are grammar
One more responsibility, and it ties back to the language of action: results are where chaining happens. If a result names things in the form another tool accepts — an id, a section number, a typed value — we have built an association into the grammar: the result invites the next move. If it comes back as loose prose, the chain breaks.
The same result, chainable and not
The second result speaks the input language of two other tools. The first speaks to no tool at all.
Look at the difference. The dead-end result gives back raw prose — to
act on it, the agent has to go read much more just to find where that
text lives. The chainable result immediately says what to read next
and which tool to hand it to: §142 is a section id, and section ids
are exactly what read_section and cite accept. The shape of a
result tells the agent which tools can use it as a parameter. When
the agent asks "what do I do next?", it looks for tools whose
parameters fit what it just received.
Design what comes back with the same care as what goes in: it is half of every tool, the half that becomes conversation.