Agents fail at tool use in predictable ways. Knowing the catalog helps you diagnose without re-running endlessly. Most fixes are at the tool definition layer, not the model layer.
Advertisement
Wrong tool selected
Two tools have similar descriptions; model picks wrong one. Fix: rewrite descriptions to disambiguate, add explicit 'use this when…' / 'don't use this for…' clauses.
Wrong arguments
Required field missing. Type wrong. Value out of range. Fix: schema constraints (model can't emit invalid JSON), descriptive error messages that the model can use to retry.
Advertisement
Right tool, wrong moment
Agent calls a side-effecting tool too early in the flow. Fix: tools that should be gated emit 'are you sure?' wrappers; or tool description includes 'only call after verification'.
Most tool-use failures are description or schema problems, not model problems. Fix at the tool definition layer.