An agent doesn’t pick the wrong tool because the model is dumb. It picks the wrong tool because your description didn’t tell it what you actually know and it didn’t.

The model only sees the description

When an agent decides which tool to call, it’s reading the tool’s name, its parameter schema, and its description — nothing else. It doesn’t see your code, your comments, or the assumptions in your head about when this tool is appropriate. If two tools sound similar from the outside, the model will confuse them exactly as often as a new engineer would reading the same two one-liners.

Bad:

{"name": "search", "description": "Searches for information."}

Better:

{
  "name": "search_internal_docs",
  "description": "Search the company's internal knowledge base (Confluence, internal wikis, runbooks). Use for questions about internal processes, architecture decisions, or how our systems work. Does NOT search the public internet or customer data."
}

The second version tells the model what’s in scope, what’s out of scope, and when to reach for it instead of a similarly-named tool. That negative space — what it’s not for — is usually the missing piece when an agent picks the wrong one out of several plausible options.

Name collisions are worse than bad descriptions

If you have get_user and fetch_user, doing slightly different things, expect the agent to mix them up under load — not because it can’t read, but because the names carry almost no distinguishing signal and it’s guessing from a coin flip’s worth of information. Rename for maximum distinction: get_user_profile vs get_user_billing_status. Specific names reduce wrong-tool-calls more reliably than longer descriptions do, and cost nothing.

Parameters need descriptions too, not just types

A schema that says {"date": {"type": "string"}} tells the model nothing about the format. Is it 2026-09-16? 09/16/2026? A Unix timestamp? The model will guess, and guess inconsistently across calls. Always specify format in the description:

{"date": {"type": "string", "description": "ISO 8601 date, e.g. 2026-09-16"}}

Too many tools is its own failure mode

Past roughly 15-20 tools in one agent’s toolset, selection accuracy drops — the model has more plausible-looking options to choose wrong between, and the tool list itself eats context budget on every single call. Two ways out:

• Split into focused toolsets loaded per task type, if your framework supports scoped tool availability, rather than exposing everything all the time.
• Consolidate near-duplicate tools. If create_ticket and create_bug differ only by a type field, that’s one tool with a parameter, not two tools competing for the same intent.

Errors are part of the interface

When a tool call fails, what comes back matters as much as what a successful call returns. {"error": "failed"} gives the agent nothing to act on — it’ll likely retry the exact same call and fail again. {"error": "user_id not found — check that the ID is a UUID, not an email address"} gives it something it can actually correct on the next attempt. Write your error messages for the agent the way you’d write them for a junior developer debugging blind, because functionally, that’s what’s reading them.

The debugging move that actually works

When an agent keeps calling the wrong tool, don’t rewrite the prompt first. Read the tool descriptions as if you’d never seen the codebase, cold — no memory of what each one does. Half the time the fix is a name change or one clarifying sentence, not a prompt engineering exercise, and it’s a smaller, more durable fix than instructing around a description problem forever.