06. How Tool Results Should Return to the Model

When a model emits pwd, it does not know which path the command will return. Execution occurs outside the model and does not update model state automatically.

A second model request is required:

task → proposed call → runtime execution → result delivery → next decision

Without the call record, the model may not know which action produced a result. Without the result, it can only guess. Showing raw output directly to the user prevents the model from combining evidence or formatting the required answer.

A result is more than appended text

The durable trace can retain the full structure while the model-facing representation is compressed. Reusing one already-truncated string for both destroys the original debugging evidence.

Four delivery strategies

A 100 KB log should not enter context by default. Store the original and return line count, error lines, head and tail samples, and a content reference. The model can request a range when needed.

Truncation must be explicit

A result reports original bytes, returned bytes, truncation point, retained region, and a method for retrieving the rest. “No error was found” is different from “the unreturned region may contain an error.”

Parallel results remain independent

Kimi’s second request contained two role=tool messages referring to Bash_0 and Bash_1. Identity, not completion time, joined each result to its call.

If one parallel call succeeds and another times out, the batch cannot collapse into one failure value. The model needs each status to retry only the failed item.

Summaries point back to evidence

Every summarized fact should refer to a log range, file-fragment identifier, or result-object path. When an answer is wrong, the trace can distinguish a tool error from a summarizer error and a later reasoning error.

The summarizer itself follows a result contract containing facts, uncertainties, omitted ranges, and the original result reference. A fluent paragraph alone hides missing information.

Strategy depends on tool semantics

Directory listings fit structured arrays. Command logs fit head-and-tail retention plus extracted error lines. Search results fit itemized summaries with sources. Binary artifacts return metadata and a reference.

One character limit for every tool discards different critical evidence. Regression tests include encoding failures, empty output, repeated fields, and one extremely long line.

Measuring the tradeoff

Run the same tool at 1 KB, 100 KB, and 1 MB under all four strategies:

The objective is neither minimum output nor maximum completeness. It is a verifiable boundary among evidence, context cost, and recovery.

Budget for the next decision

MCP supports text, structured content, resource links, and outputSchema validation. MCP Tools specification

Truncation tests place the decisive fact at the beginning, middle, and end, then compare head, tail, and relevance selection. Each result records original bytes, retained ranges, encoding, source reference, and reason.

Summary fidelity probes check error codes, files, object counts, and receipts. Identifiers remain verbatim. The measurement unit is the full Agent loop: a short summary that causes three repeated calls can cost more than one complete result.