You will be able to write tool names, descriptions and parameter schemas that lead to correct calls.
Marcus's first two tools were called lookup and convert. The descriptions said "Looks up data" and "Converts values". Within an hour of testing, the model had called lookup with the argument "grinder" to check an order, called convert with an amount and no currency, and answered a question about the returns policy by calling lookup on the word "returns". Every one of those calls was the model doing its best with what he gave it.
The model chooses tools from their names, descriptions and parameter schemas, and from nothing else. If those are vague, its choices will be too. This lesson is about writing them well.
Picture a new part-timer on their first day, with a list of buttons and one line about each. What would they need to know to press the right one? That is what a tool description should say.
A good description covers what the tool does, what it returns, when to use it and when not to. Here is Marcus's rewrite for the order tool, in plain words. Name: get_order_status. Description: Returns the shipping status and tracking number for one customer order. Use it when a customer asks where their order is or when it will arrive. Do not use it for stock questions or prices. If the customer has not given an order number, ask them for it instead of guessing.
That last sentence matters as much as the first. Telling the model when not to call a tool, and what to do when it lacks an argument, prevents most of the strange calls Marcus saw.
Each parameter needs a clear name, a type, a description and, where it applies, a unit or format.
Marcus's currency tool had two parameters called value and to, and the model had to guess what each meant. His rewrite has amount_sgd, a number, described as the price in Singapore dollars; and target_currency, an enum with the values MYR and IDR. The name says the unit, and the enum means the model cannot ask for a currency Marcus does not support.
Formats matter most for dates, times, phone numbers and IDs. If a tool takes a date, say so explicitly: a date in the format YYYY-MM-DD. Otherwise you will get "next Friday", "14/3" and "March 14" from different calls, and your code will have to cope with all of them. Order numbers deserve a format note too: digits only, no hash sign.
Mark which parameters are required. A required parameter tells the model it cannot call the tool without that value, which nudges it to ask the user instead of inventing one.
It is tempting to give the model a tool for each table, another for each kind of search and a few more for edge cases. Each description travels with every request and costs tokens, but the bigger problem is choice. When two tools could both plausibly answer a question, the model has to guess between them, and its guesses will vary.
Marcus at one point had search_products, find_product, get_product_details and check_stock. Even he could not have said exactly when to use which. The model guessed differently each time. He merged them into get_product, which returns details and current stock for one product by name or code, and 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.
A good test: could you write a description for each tool that says when to use it and not the others? If two descriptions would sound the same, merge the tools.
Tools fail. An order number does not exist, a product name matches nothing, the courier's system is down. What your tool returns in those cases matters, because the model reads it and decides its next step.
A bare "Error" or an empty result leaves the model guessing. It may retry the same call or invent an answer. A clear message gives it something to act on. Marcus's order tool now returns messages like "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 that on to the customer, who finds the missing digit.
Write error messages for the model the way you would for a user: what went wrong and what to do next. Never return a raw stack trace or a database error, since those can leak details about your system into the conversation.
Well-written tools are less work to check, but they still need checking, which is the subject of lesson 4.3. First, the activity below asks you to write two tool definitions of your own.
Write definitions for two tools, such as a currency converter and an order lookup, with descriptions, parameters and formats.
Junxiong-WFG Organisation is an authorised representative of AIA Financial Advisers Private Limited (Reg. No. 201715016G).