Your AI agent keeps calling the wrong tool

Your AI agent was supposed to do the work - look up the order, issue the refund, book the slot. Instead it calls a tool that does not fit the request, passes an amount field as the word 'full' instead of a number, or hits a tool that throws and then answers as if it succeeded. The reflex is to blame the model and swap in a bigger one. That rarely helps, because most tool-calling failures are not the model being dumb - they are tools that were described badly, arguments that were never validated, and an error path that does not exist. All three are yours to fix.

The three ways tool calling actually breaks

Before you change models, get specific about which failure you have. Almost every misfire is one of these three, and each has a different fix.

• Wrong tool chosen. The agent had 'issue_refund' and 'issue_store_credit' and reached for the wrong one, because their descriptions overlapped or the names did not make the difference obvious. When two tools sound alike, the model guesses.
• Right tool, wrong arguments. This is the most common one. The model calls the correct function but sends a string where a number belongs, an order ID that does not exist, a date in the wrong format, or leaves out a required field. The call looks valid and blows up at execution.
• The call runs but the handling is fragile. The tool returns an error, times out, or half-succeeds, and your code either crashes or, worse, swallows it and lets the model narrate a success that never happened. A tool that can fail needs a defined path for failing.

Notice that only the first is really about the model's judgement. The other two are engineering problems on the wiring around the model - which is good news, because those you control completely.

Design tools the model can actually call correctly

The model chooses and fills a tool from the schema you give it - the name, the description, the parameter definitions. Sloppy schemas cause most wrong-tool and wrong-argument errors, so this is where the highest return is.

• Keep the toolset small and non-overlapping. Every extra tool is another chance to pick wrong. If two tools do nearly the same thing, merge them or make the boundary sharp in the name and description. A focused set of five clear tools beats fifteen fuzzy ones.
• Write the description for the model, not for you. Say exactly when to use the tool and when not to. 'Use only for refunds to the original payment method; for anything else use issue_store_credit' removes the ambiguity that makes the model flip a coin.
• Constrain the parameters. Use enums for fixed choices, mark required fields as required, give types and formats, and state units and ranges in the description. A status field defined as an enum of three values cannot come back as free text. This is the same discipline that makes reliable structured output work - a tight schema is the guardrail.
• Give one example per non-obvious tool. A single worked example of a correct call in the description does more to fix argument formatting than a paragraph of prose.

Validate arguments before you execute - always

Here is the rule that prevents the largest class of production incidents: the arguments the model sends are untrusted input, exactly like a value from a web form. Never pass them straight into a database write, a payment call, or a shell. Validate first, every time.

• Re-check against the schema in code. The model was asked for the right shape; confirm it actually delivered it. Types, required fields, formats, and value ranges all get checked before anything runs. If the amount should be a positive number under a ceiling, enforce that - do not assume.
• Verify references exist. If the model passes an order ID or a customer ID, look it up before acting on it. A hallucinated ID that you never checked is how an agent 'refunds' an order that does not exist.
• Fail into a retry, not a crash. When validation fails, do not throw and die. Return the specific problem to the model - 'amount must be a number in rupees, you sent full' - and let it correct the call. Models fix a clearly-described argument error on the next turn most of the time.

Recover when a tool call fails

Even with clean schemas and validation, tools fail for reasons that have nothing to do with the model - an API is down, a record is locked, a request times out. A production agent needs a plan for that moment, not a stack trace.

• Return errors as data the model can use. When a tool throws, hand the error back to the model as a normal tool result - 'payment gateway timed out, not charged' - so it can retry, try another path, or tell the user honestly. Silently swallowing the error is what lets the agent claim a success that did not happen.
• Bound your retries. Retry transient failures, but with a hard cap and backoff. An agent that loops on the same failing call forever burns tokens and time. Two or three attempts, then escalate to a human or a safe fallback.
• Set timeouts on every tool. A tool with no timeout can hang the whole run. Give each one a deadline and treat the overrun as a failure the model can respond to.
• Make write actions idempotent. If a retry might re-run a charge, a refund, or an order, you need an idempotency key or a dedupe check so the second attempt is a no-op. This is the single most important safeguard once an agent can move money or change records. It pairs with the permission discipline in scoping what your agent's tools can touch - least privilege limits the blast radius, idempotency stops duplicate damage.

The order of work

Start by logging the actual tool calls your agent makes on the requests that fail, and read them - the failure type is usually obvious in seconds. Tighten the tool schemas first, because that is the cheapest fix and it removes whole categories of error. Add argument validation in code so nothing unchecked ever executes. Then build the failure path - errors as data, bounded retries, timeouts, and idempotency on every write. Only after all of that is it worth asking whether the model itself is the limit. This is how we wire every production AI agent we build, and it is the reason the AI systems we ship act on your data without misfiring.

Frequently asked questions

Will a smarter model fix my tool-calling errors?

Only the first kind - genuinely ambiguous choices between tools - and even then a sharper description usually fixes it for free. A smarter model still sends arguments your code never validated, and still cannot recover from a tool that throws if you have no error path. Fix the schema, validation, and handling first; upgrade the model last.

How many tools is too many for one agent?

There is no hard number, but every tool you add raises the chance of a wrong pick, especially when descriptions overlap. If your agent has more than roughly a dozen tools, look for ones that can merge or that belong to a separate, more focused agent. Fewer, clearly-bounded tools almost always call more reliably than a long list.

What does making a tool idempotent actually mean?

It means running the same call twice has the same effect as running it once. You attach an idempotency key to the action, or check whether the work was already done, so a retry after a timeout does not issue a second refund or create a duplicate order. It is essential the moment an agent can change money or records, because retries are a normal part of a reliable system.

Should I let the model retry a failed call itself?

Yes, within limits. Returning the error to the model and letting it try again is how it recovers from a malformed argument or a transient failure. But cap the attempts in your own code and add backoff, so a persistently failing tool escalates to a human instead of looping. The model drives the retry; your wiring enforces the ceiling.

The short version: an agent that calls the wrong tool or passes broken arguments is almost always describing a schema, validation, or error-handling gap - not a model that is too small. Give it a few sharply-defined tools, validate every argument as untrusted input, and build a real failure path with bounded retries and idempotent writes. Do that and the misfires fall away, without the cost of chasing a bigger model that was never the problem.