Agent failures often come from tool design, not the loop
The basic loop inside an AI agent is usually short and simple, so it is often not the real source of failure. Problems tend to start in the , where the agent has to act on outside systems. A one-line tool description gives the model too little guidance about inputs, , and the shape of the result.
Anthropic’s tool-use guidance also says detailed tool descriptions are a major factor in tool and recommends several sentences for each tool. Too many similar tools can also cause errors. If create, update, and delete actions are split into separate tools for the same resource, the model has to choose between them every time.
Grouping related actions into fewer, clearly named tools with an can reduce wrong-tool choices. that return huge raw blobs also waste tokens and make it harder for the model to use only the needed information.
Key points
- are often not the main source of bugs.
- Tool descriptions should spell out inputs, , and returned results.
- Too many overlapping tools can make the model choose the wrong one.
- Related actions can be grouped into fewer tools with a clear .
- Large raw can burn tokens and raise cost.