Everyone demos function calling with two tools and perfect JSON. Production has forty tools, ambiguous names, overlapping purposes — and a model that confidently calls the wrong one with malformed arguments. Tool use is the least reliable part of most agent systems, and it deserves the most engineering.
Design the tools, not the prompt
The first fix is tool design, not prompt design. Fewer, broader tools beat many narrow ones: one well-designed `search_documents` beats `search_pdfs`, `search_docs`, and `search_wiki`. Names must be unambiguous to a model reading them cold — `get_customer_by_id` beats `fetch_entity`. Descriptions should say when NOT to use the tool, not just when to use it; negative guidance cuts misfires dramatically.
Validate everything at the boundary
Second, validate everything at the boundary. Schemas are contracts: reject malformed arguments with a clear error message and let the model retry, rather than passing garbage downstream. We log every tool call with its arguments, latency, and outcome — the tool-call trace is where agent debugging actually happens.
Design for the model's actual behavior
Third, design for the model's actual behavior. Models pick tools by description similarity, so tools with similar descriptions get confused. They fill optional parameters with hallucinations, so make parameters required-or-absent with no tempting optionals. They struggle with more than a handful of choices, so group tools by task phase and only expose the relevant group at each step — an agent doing research doesn't need the billing tools in context.
Expect partial failure
Fourth, expect partial failure. Tools time out, return empty, return junk. Each tool needs a documented failure contract: what "no results" vs. "error" looks like, and what the agent should do in each case. An agent that treats every tool error as "try again" will retry itself into a very expensive hole.
Get tool use right and agents become boring in the best way — reliable. That's the standard we build to: tools as engineered contracts, not demo props.
Field note: The 40-tool disaster was a client's internal agent: tools named `get_data`, `fetch_data_v2`, and `retrieve_info` — the model picked randomly among near-identical descriptions. We consolidated to nine tools with unambiguous names and "when NOT to use this" guidance, then grouped them by phase: research tools visible during research, action tools only after a plan existed. Misfire rate dropped from 31% to 6% on the eval set, with zero prompt changes. The prompt wasn't the problem; the tool surface was. When your agent misbehaves, audit the tools before you touch the prompt — the model can only choose well from choices that are actually distinguishable.
