Tool use: the tool called with the wrong argument

A shop assistant agent has one tool, get_order_status. The definition the model saw was one line: get_order_status(query: string), described as "Looks up an order". A customer wrote: "Where is my order? It's 88213, name is Dana Ruiz." The model called the tool with query="Dana Ruiz". The tool returned {"error": "order not found"}. The agent then replied: "Your order is on its way and should arrive tomorrow!" The run ended with status success.

Two things went wrong in five lines. The call was wrong, and after it failed the reply was made up. The customer got a delivery date that nobody had looked up. This is the run behind the live challenge for this lesson, so the trace below is the one you will tap.

Start with line 3, the call. The model did not misread the message; the order number is right there. It guessed because the tool definition gave it nothing to go on. A parameter called query, typed as a string, with no description and no example, could mean a name, an email or a number. The model picked the name. Any model will pick wrong some share of the time, because the contract never said.

The definition is the root, and the call is where it shows. In the challenge both lines count as a right tap. Then look at line 5. The tool said not found, and the model wrote a cheerful reply anyway. Models are trained to be helpful and to keep the conversation going. An error that comes back as plain text, with no instruction about what to do with it, gets treated as a bump in the road, not a stop. That second bug is the subject of lesson 1.5. Here the point is that a bad contract causes it: a precise contract would have produced a good call, a real result, and nothing to invent.

Write the tool definition the way you would write it for a new teammate who can only read the description. Name the parameter for what it is: order_id, not query. Say what it is and what it is not: the digits-only order number, for example 88213, never a customer name or email. Mark it required, so a call without it is invalid before it reaches your code. And say what to do when the message has no order number: ask the customer, do not call the tool.

This is what Anthropic's 2025 guide on writing tools for agents says in its own words: the description is the part of the tool the model reads most carefully, and it should explain what the tool does and what to pass. OpenAI's function calling guide says the same in different words: clear names, detailed descriptions, enums where the values are known. The Berkeley Function Calling Leaderboard, which grew out of the Gorilla paper in 2023, scores models on exactly this: whether a call has the right name and the right arguments, and whether the model holds back when no tool fits. Argument errors are a measured category, not bad luck.

Then validate on your side. The schema is the first check and the runtime enforces it for free. Add a second one in code: an order id is digits only, so reject anything else before the lookup runs. When the lookup returns an error, return it as an error, not as a sentence the model can talk past. Count two numbers in production: the share of calls with invalid arguments, and the share of replies sent after a tool error. Both should sit at zero.

Say the line, the cause and the contract. "Line 3. The model passed the customer's name because the tool was defined as query with no description. I would rename the parameter to order_id, describe it with an example, mark it required, and tell the model to ask when the id is missing. Then line 5: the agent answered after an error, and I would make tool errors stop the run." Interviewers want to hear that you blame the contract before the model, and that you can name the two numbers you would watch.