Your Agent Is Calling the Wrong Tool (And Here's Why)

Your Agent Is Calling the Wrong Tool (And Here's Why) A guide to the tool-use failure modes that kill production agents — and how to prevent them. Most agents fail at tool use. Not because the LLM is bad at reasoning. Because the tool schemas are bad. I've spent months building tool-using agents for production systems and collecting failure modes. Here are the ones that will hit you, and what to do about them. Failure Mode 1: Ambiguous Tool Names If you have get_user and get_customer , your agent will confuse them. Guaranteed. Not sometimes — consistently. The fix is surgical: name tools by what they DO at the semantic level, and add explicit disambiguation to descriptions. # Bad { " name " : " get_user " , " description " : " Get user data. " } # Good { " name " : " get_user_account " , " description " : ( " Fetch internal user account details (employees, team members). " " Use for staff lookups. " " NOT for external customers — use get_customer_profile for those. " ) } The key phrase