You will be able to write tool names, descriptions and parameter schemas that lead the model to make correct calls.
Pull up one tool you have defined, or one you plan to define, and read only three parts of it: the name, the description and the parameter schema. Those three, plus any input examples you add, are where the model learns what each tool does. When it decides which tool to call, it also weighs the system prompt and the conversation so far, but the tool definition is the only place it learns what that tool is for. If the names, descriptions and schemas are vague, the model's tool choices will be vague too. When a model makes a strange tool call, it is usually doing its best with what it was given.
Marcus, an invented example, builds tools for a model that answers customer questions for a shop. Customers ask about orders, shipping, stock, prices and the returns policy. Prices are in Singapore dollars (SGD), and he converts them to MYR and IDR. He named his first two tools lookup and convert, with the descriptions "Looks up data" and "Converts values". Within an hour of testing, the model had called lookup with the argument "grinder" to check an order. It had called convert with an amount and no currency. It had also answered a question about the returns policy by calling lookup on the word "returns".
Write a tool description the way you would write one line about a button for a new part-timer on their first day. The model reads this text to decide whether to call the tool. It should cover four things: what the tool does, what it returns, when to use it and when not to use it. Then add a line saying what to do if a needed argument is missing, which is to ask the user instead of guessing. Most strange calls stop once you say when not to call a tool and what to do about a missing argument. The instruction to ask instead of guess matters as much as the first line of the description.
Marcus rewrote his order tool as get_order_status. The new description says it returns the shipping status and tracking number for one customer order. It says to use the tool when a customer asks where their order is or when it will arrive, and not to use it for stock questions or prices. It ends by saying that if the customer has not given an order number, the model should ask for it instead of guessing.
Each parameter needs a clear name, a type, a description, and a unit or format where one applies. Marcus's currency tool had parameters named value and to, so the model had to guess what each one meant. He renamed them amount_sgd and target_currency. amount_sgd is a number, described as the price in Singapore dollars. target_currency has the values MYR and IDR. With the unit in the parameter name, the model no longer has to guess. target_currency is an enum, a parameter type with a fixed list of allowed values, so the model cannot ask for a currency the system does not support.
Formats matter most for dates, times, phone numbers and IDs. If a tool takes a date, state the format explicitly: YYYY-MM-DD. Without it, one call might send "next Friday", another "14/3" and another "March 14", and your code has to handle all of them. Order numbers need a format note too: digits only, no hash sign.
Finally, mark which parameters are required. A required parameter is one the model cannot call the tool without. Marking a parameter as required nudges the model to ask the user for the value instead of making one up.
By default, every tool definition is sent with every request and billed as input tokens. The exception is tools marked defer_loading when you use tool search: their definitions are still sent on every request, but they stay out of the model's context, and do not add input tokens, until the model finds them through search. Anthropic's tool search documentation explains how this works. A bigger problem than the token cost is choice. When two tools could both plausibly answer a question, the model has to guess, and its guesses vary from call to call.
At one point Marcus had four product tools: search_products, find_product, get_product_details and check_stock. Even he could not say exactly when to use which one, and the model guessed differently each time. He merged the four into get_product, which returns details and current stock for one product by name or code. He kept get_order_status beside it. With two tools that had clearly different jobs, the model picked the right one in every test he ran that week.
To check your own set, try to write a description for each tool that says when to use it and not the others. If two descriptions would sound the same, merge those tools.
Tools fail. An order number might not exist, a product name might match nothing, or the courier's system might be down. The model reads whatever the tool returns on failure and decides its next step from that. A bare "Error" or an empty result leaves the model guessing. It may retry the same call or make up an answer.
Write error messages for the model the way you would for a user, saying what went wrong and what to do next. Marcus's order tool now returns messages such as: no order found with number 1048; order numbers have five digits; ask the customer to check the number in their confirmation email. The model passes this on to the customer, who finds the missing digit. Never return a raw stack trace or a database error, because these can leak details about your system into the conversation.
Well-written tools are less work to check, but they still need checking, and Lesson 4.3 covers how to do it. First, the activity below asks you to write two tool definitions of your own.
Write definitions for two tools, for example a currency converter and an order lookup. Include a description, the parameters and their formats for each.
Junxiong-WFG Organisation is an authorised representative of AIA Financial Advisers Private Limited (Reg. No. 201715016G).