When an agent calls the wrong tool, it's tempting to just mess with the system prompt. Often, however, the problem lies in the interface you presented to the model itself. If two tools appear to do the same thing, if the name is generic, if the description does not explain the usage boundary, or if the schema accepts ambiguous states, the agent is trying to route an intent over an ill-defined surface.
Tool calling works best when the tool definition serves as both a software contract and a routing signal. The model needs to decide whether to call a tool, which one to use and with which arguments. These three decisions can fail separately. Just fixing JSON validity doesn't solve a bad selection, and writing a perfect description doesn't make up for a schema that allows invalid combinations.
The error occurs before execution
There are at least two types of failure that usually appear together. The first is selection error: the agent chooses a tool that does not correspond to the user's intention. The second is a parameterization error: the chosen tool is the correct one, but the arguments arrive incomplete, with the wrong type, a value outside the domain or a meaningless combination.
This separation changes the diagnosis. If the agent calls get_user_by_email when it should call get_order_by_id, tightening the order_id schema does not fix the root cause of the problem. The definition of the two tools needs to make the semantic boundary explicit. If the agent chooses get_order_by_id, but sends a generic id field that the API does not accept, then schema and validation take priority.
Start with the name: describe action and object
Names that are too short save few tokens and cost a lot in ambiguity. search, lookup, fetch and get are useful verbs, but they hardly help when they appear repeated in several tools. A name like search_data forces the model to infer the domain; crm_find_customer_by_email already anticipates system, object, operation and search key.
The same goes for close pairs. get_user and get_customer might seem equivalent if the description doesn't say that user is an authenticated product account and customer is a CRM business record. list_orders and search_orders can also compete if one returns orders from a known customer and the other does a global filter search.
A good rule of thumb is to ask if a person who has never seen your application would be able to choose between two tools by reading only the name, description and parameters. If the answer requires tacit knowledge from the team, that knowledge needs to be included in the definition.
The description is part of the router
The current documentation from the main providers converges on one point: clear and specific description is not decoration. It tells you what the tool does, when it should be used and how its parameters should be interpreted. Anthropic goes further and recommends very detailed descriptions, including when to use, when not to use, meaning of parameters, and relevant limitations. OpenAI also advises explaining purpose, parameter format, expected output, examples, and edge cases when they help fix recurring crashes.
The difference between a weak description and a good definition is often borderline. “Fetch an order” says the ability. “Search for an order by its already known unique identifier; do not use it to find orders by email, date, or customer name” says capability and exclusion. It is this second part that reduces competition with neighboring tools.
Write down when to use it and when not to use it
For competing tools, include positive and negative signs in the description. A tool to search for users by email may say that it should only be used when the user's email is available. The tool for ordering by ID may say that it requires an order identifier and is not used to discover this ID. If the user's intention is “what was my last purchase?”, neither should pretend to be able to respond without first locating the customer and listing the orders.
This detail also avoids the pattern in which the model chooses the tool “most similar by name” and improvises parameters to make it fit. The more clearly the definition admits that a tool does not solve certain cases, the easier it is to forward the request to the correct alternative or ask for missing information.
The schema does not choose the tool itself, but eliminates invalid calls
Once the semantic boundary is clear, the schema needs to transform intent into arguments without opening up unnecessary space. Specific types, required fields, enums and well-structured objects reduce combinations that the runtime would have to reject later.
Consider an order status update. A status field as a free string accepts shipped, shipped!, sent, send and any other text. An enum limited to pending, paid, shipped, and canceled communicates the domain and makes states outside the contract unrepresentable. The same reasoning applies to units, channels, search modes, identifier types and possible actions.
In OpenAI, strict mode is recommended for reliable schema adherence. In this mode, objects must block additional properties and fields declared in properties must be marked as mandatory; an optional field can be modeled as accepting null. This improves structural compliance, but it does not guarantee that the model chose the right tool or that a semantically incorrect value was correct just because it passed the type.
Make invalid states difficult to represent
Permissive schemas transfer decisions to the model. Imagine toggle_light with two booleans, on and off. The combination on=true and off=true is syntactically possible and semantically absurd.
A single action field with enum on and off removes the invalid state. This engineering principle is especially useful in tool calling because each extra degree of freedom becomes another chance for the model to produce a call that is acceptable to the parser and wrong for the business.
When two tools compete, maybe they should become one
Not all ambiguities can be resolved with greater descriptions. Sometimes the tool surface is too fragmented. If create_pr, review_pr, and merge_pr share the same resource, authentication, and context, it might make sense to consolidate operations into one tool with a very restricted action parameter. Anthropic recommends this type of consolidation to reduce selection ambiguity in tool sets.
But consolidating everything also has a cost. Operations with very different permissions, irreversible effects or different preconditions may require separate tools for the runtime to apply specific policies. The criteria is not “fewer tools at any price”; is “less semantic overlap”. If two tools have the same description phrase, changing only one noun, it is worth reviewing the design.
Fewer active tools, less clutter
Even excellent definitions lose clarity when the model receives a huge catalog of similar options. OpenAI recommends keeping the initially available pool small and suggests evaluating different quantities, with fewer than twenty functions at the start of a shift as a flexible benchmark. Google recommends keeping the active set to around 10 to 20 tools. When the catalog is larger, search engines, deferred loading, or step-wise restriction may expose only the relevant subset.
This is especially important in agents with clear phases. At the authentication stage, there is no reason to let a reimbursement tool compete with identification tools. After the request has been located, the application can enable query, cancel or update tools for that context. The orchestration layer itself can do part of the routing instead of delegating the entire taxonomy to the model in a single turn.
In OpenAI, for example, tool_choice and authorized_tools allow you to restrict the set that the model can call at a given time. The gain doesn’t just come from “obeying more”; comes from removing candidates who should not participate in that decision.
A before and after of ambiguous definition
Imagine a tool called search with the description “Search customer data” and parameters query:string and type:string. It seems flexible, but the model has to guess what type means, what values are valid, when to use the search and what comes back. If there is another tool called lookup next to it, the competition becomes almost arbitrary.
The most predictable version could be called crm_find_customer_by_email. The description would explain that it looks for exactly one customer record using the standard email, that it should only be used when the email is available, that it does not search for orders and that it returns the customer_id necessary for subsequent steps. The schema would have email:string with the expected format and no generic mode field.
For orders, another tool could be orders_get_by_id, requiring order_id and explicitly saying that it does not discover orders by customer. If the user did not provide order_id, the description points to the need for another step. The model stops choosing between “search” and “lookup” and starts choosing between operations with understandable boundaries.
Examples help when correcting a real pattern
Example calls are useful when the structure is nested, formats are sensitive, or there is a repeating mess. Anthropic offers input_examples as an optional part of the tool definition. OpenAI also suggests examples and edge cases for recurring failures, with the caveat that additional examples may not help all reasoning models equally.
The point is to use examples as a boundary test, not as an infinite catalog. If a search engine accepts date_range, an example may show the correct format. If two tools are confused, contrasting examples might show a request that should call each and a third that should call neither. The effect needs to be measured, because a very specific example can also induce behavioral overfitting.
Validate the call before executing
Even a well-defined schema does not replace validation at runtime. Google recommends validating function calls before execution. In practice, this means checking types, enums, identifiers, permissions, user scope and business preconditions before touching an external system.
This layer is essential for operations with side effects. A validly formatted order_id may belong to another customer. A status allowed by the schema may not be allowed in the current request phase. A valid email address may be a recipient that the user has not authorized. Tool calling must produce a structured intention; final authorization remains the responsibility of the code.
Test tool calling as a routing problem
Evaluating only whether the final task “worked” hides where the failure occurred. A better test suite records, for each prompt, which tool was expected, what would be acceptable alternatives, whether no tool should be called, and which arguments are required. From there, you can separate selection, structure and execution.
A confusion matrix is especially useful for ambiguous pairs. Put get_user_by_email and get_order_by_id as classes and run requests that vary only the decisive sign: email present, order_id present, both present, neither present, indirect reference to “my last order” and request to update a record. If most errors always migrate from the first to the second tool, defining one of them is probably capturing language that is too broad.
The correct selection rate is a straightforward metric, but it should not stand alone. Also measure schema validity, semantically correct arguments, unnecessary calls, omitted calls, repetition of the same tool, latency and cost. An agent who gets 98% of the tool right but creates two extra calls per task may be worse off for production than one with the same accuracy and more disciplined flow.
Research from 2026 reinforces that the catalog matters
Recent work helps explain why this care is not just about API aesthetics. The ToolMATH benchmark was designed precisely to evaluate environments with large catalogs and overlapping tools. The authors noted that redundancy doesn't just work like noise: similar candidates can amplify small initial deviations and push the agent onto wrong trajectories in multi-step tasks.
Another work from 2026, To Call or Not to Call, shows that the decision to use a tool can also be suboptimal even when tool use improves results on average. The study separates necessity, utility and cost of the call and shows that models can call tools when they are not needed or fail to capture the available gain. For engineering
agents, the practical reading is clear: it is not enough to check whether the tool exists and works. It is necessary to measure whether she was chosen at the right time and whether it was worth calling her.
What is portable between OpenAI, Claude and Gemini
API details change, but most of the engineering is portable. OpenAI, Anthropic and Google treat name, description and schema as a central part of the function calling interface. All three value descriptive names, specific parameters and sufficient context for the choice.
The differences appear in the controls. OpenAI offers strict schema adherence and mechanisms to limit allowed tools. Anthropic emphasizes long descriptions, input_examples, namespacing, and consolidation of related operations. Gemini recommends clear descriptions, descriptive names, strong typing with enums, limited active set, and validation before execution. In all cases, the most important principle is not to rely on a vague phrase in the prompt to correct an ambiguous API.
A practical diagnosis for the next failure
When the agent calls the wrong tool, preserve the case as a test. First confirm if there was more than one plausible tool according to the definition. Then compare names and descriptions looking for overlap in verb, object and usage condition. Then check whether the schema contains generic fields that push decisions to free strings or contradictory booleans. Finally, reduce the active set and run the same case again with neighboring examples.
If the selection improves only when the competing tool is removed, the problem is a boundary problem. If the correct tool is chosen, but the arguments are still bad, press types, enums, required and validation. If the agent insists on calling a tool even when none is needed, include “no call” cases in the evaluation and review the routing instructions. The goal is to turn an anecdotal failure into a reproducible test.
Interface clarity wins over prompt patch
Reliable tool calling is born from a surface of actions that makes sense even before the model enters the scene. Names tell you what the operation is. Descriptions delimit when it applies and when it does not apply. Schemas eliminate invalid states. The runtime validates what the schema cannot guarantee. And the tests show where two tools still compete.
When these elements are well designed, the agent's prompt no longer bears the responsibility of “guessing the right tool” alone. The model receives more distinct options, produces more verifiable arguments, and the team can measure correct selection rather than expecting a happy demo to represent behavior in production.
