Before you blame the model, read what it's actually shown about each tool. Usually that's a name and one thin sentence, and a person handed the same sentence would be guessing too.
- The model sees only a tool's name, description and argument schema, so anything you leave out of those three it has to guess.
- A description that works says what the tool does, when to use it, when not to and which tool to use instead, and what comes back.
- Anthropic's engineers wrote that refining tool descriptions helped Claude Sonnet 3.5 reach state-of-the-art on SWE-bench Verified.
- Overlapping tools cause more wrong calls than weak models do, so merge them or draw a hard line between them in the text.
- A set of 40 prompts with the correct tool labelled on each lets you measure a rewrite in one afternoon.
Most wrong tool calls start with the person who wrote the tool, not the model that made the call. That's the case for learning how to write AI agent tool descriptions before you spend a cent on a bigger model. Anthropic's engineering team said in its post on writing tools for agents that Claude Sonnet 3.5 reached state-of-the-art on SWE-bench Verified after the team made precise refinements to its tool descriptions. The gain came from the words around the tools.
It's also the cheapest experiment in agent work. You don't need new infrastructure, a fine-tune or a bigger budget. You need an afternoon and a list of prompts.
The model never sees your function body. It gets a name, a description and a JSON schema for the arguments, and it picks from those alone. Whatever you know about the tool and haven't written there, the model has to guess, and it guesses with total confidence.
Take two tools called search_docs and search_tickets, described as 'Searches documents' and 'Searches tickets'. A user asks what the company promised Acme about uptime. The answer could sit in a contract PDF or in a support ticket from last spring. Read only those two descriptions and you couldn't choose either, so a coin flip between them isn't a model failure. Frankly, if you can't pick the right tool from the description alone, don't expect a model to.
Why Does My AI Coding Agent Bill Keep Increasing Overnight Why does my AI coding agent bill keep increasing when nobody touched the keyboard overnight? Usually it's a runaway tool-call loop compounding token costs with every retry. This guide walks through the mechanism, a real incident involving Replit's agent, and the specific guardrails that stop it. - why AI coding agent bills spike overnight - preventing runaway tool call loops in agents
Anthropic's tool use documentation tells developers to aim for at least three or four sentences per description, and more for tools with edge cases. A one-line description is the default in most tutorials, which is how it ends up in production. The same engineering post says to describe a tool the way you'd brief a new hire: spell out the specialized query formats, the niche terminology and the relationships between the underlying resources that you'd normally leave unsaid.
A description that holds up usually answers five questions. What does the tool do, in plain words? When should the model reach for it? When shouldn't it, and which tool should it use instead? What comes back? What are the limits, such as a result cap or a date range? The third question is the one nearly everyone skips, and it's the one that stops wrong calls.
A before and after rewrite you can copy #
Here's a three-tool set for a customer support agent. It's an illustration, not a published benchmark. The originals read like this: get_customer, 'Gets customer info.' search_orders, 'Searches orders.' update_record, 'Updates a record.'
Now a user asks whether Dana Whitfield got her refund. The agent has three plausible doors. Customer info could reasonably include refunds, so the model opens get_customer, reads a profile, finds no refund and either says there isn't one or fills the gap with something plausible. Nothing is wrong with the model. It made a sensible choice from the evidence it was given.
Here's get_customer after the rewrite.
Looks up one customer's profile: name, plan, billing email and account status. Takes a customer ID or an email address. Use it to answer who someone is or what plan they're on. Don't use it for purchases or refunds; call search_orders for those. Returns a single customer or a not_found error, never a list.
And search_orders.
How Does the Model Context Protocol Work, and What It Kills for Startups How does the Model Context Protocol actually work, and why should founders care? MCP standardizes how AI agents connect to outside tools, and two years after Anthropic open-sourced it, that standardization is quietly commoditizing the AI integration startups whose whole pitch was doing that wiring for you. Here's the client-host-server mechanics... - model context protocol for AI agent integration - what happened to AI integration startup business models
Finds orders and refunds for one customer, newest first, up to 25 results. Needs a customer ID, so call get_customer first if you only have a name or email. Use it for questions about purchases, shipping status and refunds. Don't use it to change anything.
And update_record.
Edits one field on a customer or order, only after the user has confirmed the change. Changes are written immediately and can't be undone. Never call it to check a value; use get_customer or search_orders to read.
Look at what changed. Two of the three now name a neighbor and send the model there. One sets an order of operations, get_customer before search_orders, which no schema could have told the model. One warns that the call is irreversible. None of it is clever. It's what the author knew and never wrote down.
I won't hand you an accuracy figure for this rewrite, because any number I gave would be invented. The gain depends on how much your tools overlap and what your users ask. What I'll stand behind is the method: same prompts, same model, only the descriptions change, and you count the results. The last section walks through it.
Function calling schema design does half the work #
Function calling schema design matters as much as the prose, because a wrong argument is often a wrong tool call in disguise. Use an enum wherever the values are a closed set. A status field limited to open, pending, refunded or closed leaves the model nothing to improvise. Put a format and an example inline, such as 'date as YYYY-MM-DD, for example 2026-11-18'. Name parameters for what they hold: customer_email beats user every time. Say which fields are required and what the default is for the rest. Tool output belongs in the design too. Anthropic's team reported that swapping opaque identifiers for meaningful names in tool results improved Claude's precision on retrieval tasks, and that it added a response_format option, concise or detailed, so an agent could ask for less when it only needed a name. A tool that dumps thousands of tokens of JSON on every call burns the context the agent needs for its next decision.
Then there's the error message, which is the next description the model reads. A bare 'Error 422' sends the agent back to retry the same call. 'customer_id must look like cus_ followed by 14 characters; you passed an email address, so call get_customer first' fixes the problem on the next turn. Anthropic's post makes the same case for actionable errors over stack traces.
One habit is worth breaking. When an agent picks the wrong tool, teams often patch it with a line in the system prompt, something like 'use search_orders for refunds'. Then someone splits the tool in three, and the patch is now lying to the model. Put routing rules in the description. It travels with the tool.
Why your agent picks the wrong tool even with good prose #
Overlap does more damage than vagueness. Two tools that both plausibly answer a question will split the traffic however well each one is written, and every near-duplicate you add is another place to be wrong.
Researchers behind the RAG-MCP paper tested tool selection as the pool of MCP tools grew and reported accuracy of 13.62% with every tool stuffed into the prompt, against 43.13% when a retriever shortlisted candidates first. That was a stress test with a very large pool, nothing like a five-tool support agent. The direction still applies. More tools, more confusion.
Anthropic's advice is to consolidate. Instead of list_users, list_events and create_event, build one schedule_event that checks availability and books the slot. If you can't state the difference between two tools in one sentence, they're one tool, or one of them shouldn't exist. Merge first, then describe what's left.
Naming is part of it as well. Anthropic said that prefixes and suffixes, like asana_search versus jira_search, had non-trivial effects on selection, and that the effect varied by model. Their advice was to test your own set rather than copy a convention.
Examples inside a description cut both ways. One example of a date format beats a paragraph of rules. But models copy what they see, so if your sample search is 'refund for order 1042', expect a lot of queries shaped like it. Use an example to show a format, and keep it from looking like the only valid request.
Length has a cost too. Descriptions ride along on every request, so twelve tools at about 150 words each is roughly 2,400 tokens of context before the user types a word. Cache the tool block if your provider supports it, and trim sentences that don't change a decision. The boundary sentence, the one that says don't use this for X, almost never gets trimmed.
Test it in an afternoon #
Pull 40 real requests from your logs. If you don't have logs yet, write them from support tickets or user interviews. Next to each, write the tool the agent should call first, or write none. Make about ten of them sit between two tools, and make five of them cases where no tool should fire at all. Those are the prompts that expose a fuzzy boundary.
Run them against your current descriptions with the same model, the temperature as low as it goes, and stop at the first tool call without executing it. Score tool selection separately from arguments, because they fail for different reasons. Selection accuracy is just right calls divided by 40. The total matters less than the confusion pairs, meaning which two tools keep getting swapped. In most sets, one or two pairs account for the bulk of the misses.
Rewrite only the descriptions for the worst pair, then rerun. Change one pair at a time or you won't know what worked. Hold back ten prompts you never look at while editing, so you aren't just teaching your descriptions to pass your own test.
If the numbers don't move after a real rewrite, you've earned the right to look at the model, the system prompt or the tool count. Most teams never reach that conclusion honestly because they skipped the experiment. Start with the pair your logs show swapped most often, rewrite those two descriptions, run the same 40 prompts again, and put the before and after numbers where your whole team can see them. Also read: How to Compare LLM API Cost Per Million Tokens Before You Pick a Model • How to Calculate Cost of Goods Sold for AI Startups Before Diligence Does • How to Calculate Annual Contract Churn Lag Before Renewals Expose It
This article is posted in AI News, check it out for more related stories.
Join the discussion #
Open in the community → Almost there. Sign in and your reply posts straight away.