Tool Result Normalization

What it is

Turning whatever a tool actually returned into the one shape the agent loop consumes: a consistent envelope distinguishing success from failure, a payload reduced to what is usable within a context budget, provenance that survives the conversion, and an explicit marking of the content as data rather than direction. The inputs are as varied as the systems behind them — nested JSON, a page of HTML, a binary attachment, a stack trace, an empty body with a status code — and the output has to be uniform enough that one loop handles all of it.

Why it matters

Every result is read by a model that cannot ask what a field means and will not notice that something is missing. Shape inconsistency costs accuracy directly: if one tool signals failure with a status field and another with an empty list, the model learns neither convention and guesses. Size costs money and quality, because the result is re-read on every subsequent turn and a large one crowds out the conversation. And because results are the main channel through which text from outside the system enters the model's context, how they are wrapped is a security decision, not only a formatting one.

Reshaping output versus enforcing a contract

Validation compares what arrived against what was declared and rejects the mismatch; it is a gate with a yes or no. Normalization accepts what arrived, including the half of it that no contract described, and converts it into something usable — selecting fields, flattening, truncating, redacting, re-labelling. A result can be perfectly valid against its declared schema and still be a 900-row array that will destroy the turn. The two run in sequence and neither substitutes for the other.

Key decisions

• The envelope. One shape for every tool, carrying an explicit outcome status, the payload, a short failure reason where applicable, and metadata such as truncation, timing, and source.
• Where failures live. In-band in the envelope, so the model always receives a readable result, is almost always right; out-of-band exceptions produce loops that cannot recover.
• Reduction strategy per tool: projecting known-useful fields, truncating with a stated marker, or summarising with a model. Projection is cheap and lossy in predictable ways; summarisation is expensive and lossy in unpredictable ones.
• Whether the full payload is retained outside the context and addressable by a handle, which is what makes aggressive reduction safe.
• What is redacted before anything enters context, given that whatever is in context can reach the user, the logs, and the next upstream.
• How non-textual output is represented: a table serialised for reading, a reference to a stored artefact, or a description. Each loses something different.
• How provenance travels, so a statement in the final answer can be traced to the call that produced it.

Failure modes

• A single result consumes most of the context window and every later turn of the conversation pays for it, degrading as much from the eviction as from the noise.
• Truncation is silent, so the model reads forty rows as the complete set and reports a total that is wrong by two orders of magnitude.
• An HTML page is flattened to text and the table structure that carried the meaning becomes an unlabelled run of numbers.
• A failure arrives inside a successful response and is normalized as data, so the model treats an error message as the answer and presents it to the user.
• Model-generated summarisation of a result drops the one identifier the next call needed, which is invisible until the next call fails.
• Normalization strips the source and timestamp, and the final answer cannot be attributed or dated even though both were available at the point of retrieval.
• Instructional text inside a result is rendered indistinguishably from the host's own prompt, and the model follows it.
• Field names are rewritten per tool into a house style that no longer matches the identifiers the same tool expects as arguments on the next call.
• Credentials or personal data pass through into context and from there into a trace store with a long retention period.

Related capabilities

• Tool Schema Validation — judges conformance where this reshapes content
• Function Calling — consumes the envelope this produces on the next turn
• MCP Server — can bound a result before it ever needs reducing
• Tool Timeout and Retry — needs a distinguishable outcome-unknown status in the envelope
• Tool Execution Sandbox — the output crossing its boundary arrives here

Applies: Production readiness · Design questions