Improve tool calling reliability: schema design, description quality, validation, retries and idempotency, error feedback, and measuring selection accuracy.
Tool calling reliability is usually the difference between an agent demo and an agent in production. The model's reasoning is rarely the bottleneck; the failures concentrate in selecting the wrong tool, supplying malformed arguments, mishandling errors, and repeating actions that should happen once.
Most of these are engineering problems with engineering fixes.
Reduce the surface
Selection accuracy falls as the number of available tools rises. An agent choosing among eight well-scoped tools is materially more reliable than one choosing among forty granular ones.
Consolidate related operations into task-level tools. Remove tools that exist because an API endpoint existed. If a tool has not been correctly selected in evaluation, either its description is wrong or it should not be exposed.
Where a large surface is genuinely necessary, partition it across specialized agents rather than presenting everything at once.
Write descriptions as the deciding input
The model selects almost entirely from the tool name and description. Treat them as the primary interface.
State what the tool does, the conditions under which it is the right choice, the conditions under which it is not, and what it returns including limits. Explicitly distinguishing similar tools inside their descriptions prevents most confusion between them.
Name parameters unambiguously and constrain them tightly. Enumerations beat free strings wherever the valid set is known, because they turn a semantic mistake into a validation error.
Validate independently of the schema
Schema validation catches shape errors. It does not catch a well-formed request the caller had no right to make, or values that are individually valid but nonsensical together.
Validate business rules server-side: date ranges that make sense, amounts within limits, references that exist and belong to the requesting user. Enforce authorization against the end user's identity rather than a broad service credential.
Reject early and clearly rather than partially executing.
Make errors instructive
An agent recovers from an error only if the error tells it what to do differently.
Return a machine-readable code, a human-readable message naming the specific problem, and where useful the accepted values. invalid_argument: end_date must be after start_date; received start=2026-08-19, end=2026-08-01 produces a corrected retry. A bare 400 produces the same call again.
Distinguish retryable from terminal errors explicitly, so the agent does not retry a permission denial or give up on a transient timeout.
Handle retries and duplication
Agents retry, and network timeouts occur after the server has already acted. Both produce duplicate side effects unless you design against them.
Make every write idempotent using a caller-supplied idempotency key, and return the original result on a repeated key rather than performing the action twice.
Record external effects with enough detail to reconcile them. For long-running operations, return a handle immediately and expose a status tool instead of holding a connection open past a timeout.
Control loops
Set a maximum number of steps per task, a maximum number of consecutive failures of the same tool, and an overall budget. When a limit is reached, stop, preserve state, and escalate with what was accomplished.
Detect repetition explicitly. An agent calling the same tool with the same arguments three times is stuck, and continuing costs money without progress.
Measure selection accuracy
Build a labeled evaluation set from real tasks where the correct tool sequence is known. Measure how often the agent selects the right tool, supplies valid arguments on the first attempt, recovers from injected errors, and terminates appropriately.
Run it on every change to tools, descriptions, prompts, or models. Editing a description to clarify one tool routinely changes selection behavior for another, and without evaluation that regression ships silently.
Log every call in production with tool, arguments, outcome, latency, and cost, so real-world failure patterns feed back into the evaluation set.
Frequently asked questions
Why does the agent pick the wrong tool?
Usually overlapping descriptions or too many similar tools. Fix by clarifying boundaries in the descriptions and consolidating the surface.
Should we let the model retry freely?
No. Bound retries by count and budget, and require idempotency on any write before allowing automatic retry.
How do we stop duplicate actions?
Idempotency keys on writes, plus reconciliation checks after interruptions.
Do smaller models handle tool calling well?
Often adequately for narrow, well-described tool sets. Evaluate on your own tasks rather than assuming the largest model is required.
Explore our software and web capabilities or discuss your AI workflow.
Written by
Moueen Togarvi
Founder & CEO at Voquarn Code, focused on product engineering, search growth, and practical AI systems.