A tool the model calls correctly on the first try and a tool it fumbles, calling with wrong parameters or not calling at all when it should, usually come down to the same thing: how the tool was named and described, not how well the underlying code works. This is a design craft distinct from the reliability-under-load patterns covered elsewhere, and it deserves its own attention.
What makes a tool easy for the model to call correctly
This is the same discipline Anthropic's own guidance on building tools for agents recommends, and it holds regardless of which client or agent framework is calling the tool: the model only knows what the name, description and schema tell it, so precision there is doing far more work than developers coming from traditional API design usually expect.
A clear, specific name that states exactly what the tool does, a description that includes when to use it and, just as importantly, when not to, and a parameter schema with names and types that match how a person would naturally describe the inputs. A tool named "update" with a one-line description invites the model to guess at intent. A tool named "update_customer_shipping_address" with a description stating exactly what fields are required and what happens on success removes the guesswork entirely.
Specific names: describe exactly what the tool does, not a generic verb
Descriptions that state when to use it, and explicitly when not to
Parameter names matching natural language, not internal database column names
Return values that clearly confirm what actually happened
The overlap problem: too many similar tools
A common failure mode isn't a single badly named tool, it's several tools that sound similar enough that the model can't reliably tell them apart. Two tools named "send_message" and "send_notification" with vague, overlapping descriptions will get confused for each other regularly, even if each one works perfectly in isolation. The fix is either merging genuinely overlapping tools into one with clear parameters, or sharpening the descriptions enough that the distinction is unmistakable.
A worked example: fixing a confused tool set
A Melbourne SaaS team building an internal support agent had four tools for different kinds of customer record updates, all named generically enough that the model called the wrong one roughly one time in five during testing. Rewriting each name to state its exact scope, update_billing_contact versus update_shipping_contact versus update_account_owner versus update_support_contact, alongside descriptions naming the specific field each one touched, dropped the wrong-tool-call rate to near zero in the same test suite. The fix took an afternoon and no changes to the underlying logic at all.
Testing this properly before shipping
The only reliable way to know whether a tool set is well designed is testing it with realistic, varied phrasing of the same underlying request, not just the one clean example used during development. If five different plausible phrasings of the same task all correctly trigger the intended tool, the design is solid. If even one common phrasing picks the wrong tool, that's a naming or description problem worth fixing before it reaches production, not an edge case worth ignoring.
What fixing this is worth
For the Melbourne team above, the afternoon spent renaming and re-describing four tools avoided a much bigger cost: a wrong-tool-call rate of one in five in a customer-facing support agent would have meant genuinely wrong actions taken against real customer accounts regularly enough to erode trust fast, easily worth more than $10,000 in support escalations and remediation over a quarter if left unfixed. The design work is cheap. The consequence of skipping it isn't.
This is worth treating as a standard step in any tool-building process, not an optional polish pass done only if time allows. Budget the naming and description work into the same estimate as the underlying implementation, since in practice it often takes less time than the implementation itself and prevents a much more expensive class of production bug.
This discipline scales down as well as up. Even a solo developer building two or three tools for a personal project benefits from the same specific-naming, clear-scope approach, since the cost of getting it right is small and the cost of a model calling the wrong tool in a live workflow is rarely trivial.
Build this into the definition of "done" for any tool before it ships, alongside the usual functional testing, rather than treating it as a separate, optional review step that gets skipped under time pressure.
It's a cheap habit that pays for itself on the very first tool it's applied to.
Worth revisiting whenever a new tool joins an existing set, checking it doesn't reintroduce the overlap problem described above.
