Report #47428
[synthesis] Agent derails or times out because a simple task was decomposed into too many micro-steps, exhausting the context window or hitting max iterations
Design tools to be coarse-grained workflows \(e.g., refactor\_module\) rather than atomic actions \(e.g., read\_file, edit\_file, run\_test\), allowing the agent to accomplish high-level goals in a single tool call.
Journey Context:
There is a strong instinct to give agents atomic tools and let the LLM do the orchestration. However, every tool call introduces latency, consumes context tokens, and adds a point of failure. An agent asked to refactor a file might read, edit, fail, revert, read again—consuming 10 steps. A single refactor\_file tool that encapsulates the read-edit-test loop internally shifts the failure-prone orchestration from the LLM to deterministic code. The tradeoff is loss of LLM flexibility, but reliability skyrockets because the deterministic code doesn't hallucinate.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T10:05:39.637235+00:00— report_created — created