How-to · Updated 2026-10-19
How to reduce tokens in tool call output
To reduce tokens in tool call output, stop large results from entering the conversation raw. Cap and paginate at the tool, tell the agent when output was cut, offload huge payloads to a handle, and compress what remains against the current question so only the lines that answer it stay in context.
Why does tool output cost so much?
Tool results persist in the message history, so an oversized result is sent to the model again on every later request for the rest of the run. A 20,000-line test log read once is paid for on every following turn. That is why the tool boundary is the best place to intervene: reduce once, and the smaller form persists.
What should every tool do before returning output?
Vercel's tool design material describes a truncation contract worth copying: cap the output, say that it was truncated and by how much, and provide pagination parameters. A tool that silently truncates is worse than none, because the model believes it saw everything. Source: Vercel Academy, Tool Output Design. Pydantic AI's harness documents similar modes: truncate, spill to storage with a preview and handle, or summarize. Source: Pydantic AI tool output limits.
How do you handle old tool results?
Results from several turns ago rarely matter at full size. The OpenAI Agents SDK ships a ToolOutputTrimmer that leaves recent turns intact and replaces older large outputs with a short preview. Source: OpenAI Agents SDK docs. Use something like it for long sessions.
When should you compress instead of truncate?
Truncation keeps the head, the tail or both. That is wrong when the useful lines are in the middle: the one failing assertion in a long test run, the one stack frame in your code, the one row in a JSON array. Question-aware compression scores lines against what the agent is trying to do and keeps the matching lines.
With SuperCompress you send the output and the question to the hosted API:
curl -X POST https://www.supercompress.dev/api/v1/compress \
-H "X-API-Key: $SUPERCOMPRESS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"context":"<tool output>","query":"why did the checkout test fail?"}'The response includes the kept text plus original_tokens and kept_tokens. Lines are kept verbatim, never rewritten. Coding agents do not need to call this by hand: supercompress setup installs the MCP tool and hooks.
How do these techniques fit together?
- Filter at the source (query parameters, flags,
--quietmodes). - Cap and paginate with an honest truncation marker.
- Compress what is left against the question.
- Trim stale results on later turns.
Then compare your provider bill per finished task with and without each step. Fewer tokens in one place can be offset by extra retries elsewhere.
Frequently asked questions
How do I reduce tool output tokens in an AI agent?
Limit and paginate output at the tool, mark truncation clearly, offload very large payloads, trim old results, and compress the remainder against the current question.
Is it better to truncate or compress tool output?
Truncate when the useful part is at the start or end. Compress against the question when relevant lines can be anywhere, as in logs, diffs and JSON.
Does SuperCompress rewrite tool output?
No. It is extractive: it keeps original lines that answer the question and drops the others, so identifiers and error text stay exact.
Which tools produce the biggest outputs?
Test runners, build logs, web page snapshots, database queries, file reads and search results are the usual offenders.