Tool Output Budget

Tool Output Budget

Keep oversized tool output out of the main context. Replace it with a token-aware summary plus the parts most likely to matter.

When to use

Use this Skill immediately after any of these tool calls, before quoting the output in your next response:

• bash returns output that looks like a large log, JSON array, HTML page, or cat of a long file (e.g. cat huge.log, npm test 2>&1, kubectl get ... -o yaml).
• Any tool returns a single line longer than ~500 characters (typical of minified JS, base64 blobs, very wide CSV).
• The tool succeeded but the user did not ask for the full payload.

When NOT to use

• The user explicitly asked for "the whole thing" or "every line".
• The output is small (< ~3000 tokens). Trust the tool as-is.
• You genuinely need the exact bytes (e.g. computing a hash, doing a byte-equal diff). Quote the output verbatim and explain why truncation is unsafe.

Process

1. Estimate the size. If the tool already returned a byte count, use that. Otherwise, count newlines and pick the longest line. A line of ~80 characters is roughly 20 tokens.

2. Decide to truncate if any of the following hold:

   • Total estimated tokens > 3000 (default threshold).
   • Any single line > 500 characters.
   • Output structure is a long JSON array, log dump, or fetched HTML.

3. Pick what to keep. Default: head 200 lines + tail 50 lines + 1 marker line. Adapt:

   • For cat of a known file, prefer tail (errors and stack traces usually live at the end).
   • For a JSON array, prefer head (the schema is at the top; the agent only needs a few sample items).
   • For a fetched HTML page, prefer the head (metadata, title) plus a 1-line tag count summary; do not keep the body.

4. Format the replacement as a single fenced block:

   [truncated by tool-output-budget]
   kept: lines 1-200 of 1234 (head) + lines 1185-1234 of 1234 (tail)
   skipped: 834 middle lines
   estimated total tokens: ~5500
   file path on disk: <path>     # only if the tool output came from a real file
   

5. Hand back the original file path when you have it. The user may want you to re-read a specific range later, and you can use read with explicit offset / limit for that.

6. Do not silently retry the same tool. Truncation is a one-shot decision per tool result.

Output contract

Every time you apply this Skill, the user's next message should see exactly this shape:

• A short preamble explaining what was truncated and why (one sentence).
• A fenced code block with the kept head + tail + marker line.
• (Optional, only if a real file exists) The path to re-read for the full content.

Example

> cat /var/log/app.log

[truncated by tool-output-budget]
kept: lines 1-200 of 4821 (head) + lines 4771-4821 of 4821 (tail)
skipped: 4621 middle lines
estimated total tokens: ~6800
file path on disk: /var/log/app.log

# last 5 of tail (the part the user usually wants)
2026-08-23T22:47:01Z ERROR connection refused 10.0.4.7:5432
2026-08-23T22:47:02Z ERROR retrying (1/3)
2026-08-23T22:47:05Z ERROR connection refused 10.0.4.7:5432
2026-08-23T22:47:08Z WARN  giving up; will retry on next request
2026-08-23T22:47:08Z INFO  request 7d4e failed: upstream unavailable

Common pitfalls

• Don't truncate error output that contains the answer. If the user asked "why did the test fail", the failure line is in the tail of the test runner output. Keep tail, drop head.
• Don't truncate cat of source code you need to edit. Use read with offset/limit for surgical access; keep the full code in the next step's tool call.
• Don't estimate size from newlines alone. A 1-line 50 KB minified file is one "line" but ~12,000 tokens. Check the longest line first.
• Don't loop. If you truncated, the next tool call should act on the result, not re-run the same command with the same expectation.

Verification checklist

• Did you estimate tokens or bytes before deciding?
• Is the marker line present and clear about how much was skipped?
• Did you keep the part most likely to matter (head for structure, tail for errors)?
• If a real file path exists, did you hand it back to the user?
• Did the user's next step actually use the truncated result?