Only 58% of calls to search_orders succeed first time. Agents retried it 1.4 times per call on average across 892 calls.
When it fires
The denominator is calls on covered days, not all calls in range. A tool whose calls all arrived today produces no insight rather than a false one.
What it means
The model is calling your tool, not getting what it wanted, and calling it again with different arguments. See First-call success for how a retry is distinguished from ordinary repetition. This is almost never a bug in the tool. It is a gap between what your tool does and what your description implies it does.The fixes, in the order they usually work
1
Read the description as a stranger
Does it say what question the tool answers, or what operation it performs? “Search orders by customer, date range or status” beats “Queries the orders table.”
2
Check the outcome breakdown first
A high
bad_args share is a schema problem, not a description problem. A high empty share means the tool is succeeding at doing nothing. Each has a different fix, and the breakdown tells you which you have in one glance.3
Name arguments after what they mean
status beats state_flag. An enum with its values listed beats a free string. A date field with its format in the description beats one without.4
Return errors that say what to do next
An empty array tells a model nothing.
isError: true with “no customer with that id — use search_customers first” tells it exactly what to do, and turns a retry into a correct second call.5
Check the pairs
If this tool is always preceded by another, the model may be gathering an argument it cannot get any other way. See Tool pairs.
What not to do
Don’t add more tools. Splitting a struggling tool into three usually produces three struggling tools and three schemas, and gives the model three chances to pick wrong instead of one. See Schema size. Don’t loosen the schema. Accepting anything turnsbad_args into empty, which moves the failure somewhere quieter without fixing it.