Shape Tool Output For Agents
shape-tool-output-for-agents
Summary
Human-oriented tool output can bury the failure signal an agent needs to act. Prefer quiet summaries, structured output, and saved full logs so agents see the actionable slice first without losing debugging context.
Problem
Many tools produce output optimized for humans watching a terminal. Verbose progress logs, duplicated success lines, and full workspace output can bury the failure signal an agent needs.
Preferred Move
Prefer quiet commands, failure-focused wrappers, structured output, and saved logs. Show agents the small actionable summary first, with a path or command for inspecting full details when needed.
Tradeoff
Do not hide context needed to debug failures. Keep full logs available on disk and make the summary honest about truncation or filtering.
Agent Instruction
When a command is noisy, use a quiet mode or wrapper that surfaces failures first. If you filter
output, record where the full log can be inspected.Examples
Bad: a workspace test floods context with success output.
pnpm test
Good: the wrapper keeps attention on failures and preserves full logs.
scripts/test-failures-first.sh --log target/test.log
References
| Source | Use | Note |
|---|---|---|
| OpenAI context management | adapts |
Context is scarce, so agents need concise relevant signals. |