How Anthropic Redesigned Tools to Fix Agent Failures
TRIGGER
Agents using tools make avoidable errors not because the model lacks capability, but because tool definitions are ambiguous, require difficult formatting, or have parameters that invite mistakes. Teams spend time debugging agent behavior when the root cause is poor tool ergonomics.
APPROACH
Anthropic's SWE-bench agent team invested more time optimizing tools than the overall prompt. They discovered the model made mistakes with relative filepaths after changing directories—fix: changed the tool to require absolute filepaths, eliminating that error class entirely. Input: tool definitions with ambiguous parameters or complex formatting requirements. Output: redesigned tool interfaces that eliminate common model mistakes. They recommend: give models tokens to 'think' before committing to output, keep formats close to natural text (markdown over JSON for code), avoid 'formatting overhead' like accurate line counts in diffs or escaping code in JSON strings. Test tools extensively in workbench to find failure modes.
PATTERN
“If a junior developer would find your tool interface confusing, so will the model—and you'll spend weeks debugging "agent failures" that are actually API design failures. Apply HCI rigor to agent-computer interfaces: eliminate ambiguous parameters, require absolute paths, prefer markdown over JSON.”
✓ WORKS WHEN
- Agent performs multi-step tasks where tool errors compound across steps
- Tools have parameters that could reasonably be interpreted multiple ways (relative vs absolute paths, diff formats vs full file rewrites)
- You can iterate on tool design based on observed failure patterns in testing
- Tool usage is frequent enough that small error rate improvements have meaningful impact
✗ FAILS WHEN
- Tools are simple with unambiguous parameters (single boolean flag, constrained enum)
- Agent only makes single tool calls without chaining
- Tool failures are easily recoverable and don't compound
- Constraints require formats that are inherently hard for LLMs (e.g., must output valid diffs for legacy system integration)