Why does my agent keep picking the wrong tool?

An agent has twelve tools on the page and it keeps calling update-record when the user asked to archive-record. Nothing is broken in the schema. Both tools exist, both are described correctly in isolation, and the model still picks wrong more often than feels reasonable. The usual response is to add a stricter system prompt, or a longer description on the tool that keeps losing. Neither addresses the actual problem, which is that the model is choosing between too many similar-sounding options on every single turn, and the descriptions read like a catalogue rather than a set of instructions for telling one thing from another.

Every tool descriptor is a prompt

This is easy to forget because tool definitions live in a schema, not in the chat transcript, so they feel separate from "the prompt". They are not. Whether you are working with MCP's tool descriptor shape (name, description, input schema) or WebMCP's page-level registration, the full text of every registered tool's name, description and parameters gets serialised into context on every turn the model might need to call one. Ten tools with a paragraph of description each is a few hundred tokens before the user has said anything. Thirty tools, each with a careful explanation of edge cases, is a meaningful chunk of the context window spent on options the model will not use this turn. That cost is not just financial. It is attention. The model has to read all of it to decide which one applies, and the more it reads, the more surface area there is for two descriptions to look close enough that the choice becomes close to arbitrary.

Past roughly a dozen, selection gets shaky

There is no exact cliff edge, but the pattern shows up consistently once a session has more than about a dozen tools registered simultaneously: the model starts substituting a plausible neighbour for the correct tool, or hedges by calling a general-purpose one instead of a specific one. Some hosts do not even let it get that far. Past a certain count, they will silently drop tools from what gets sent to the model, keeping the ones that fit some priority order and quietly discarding the rest. Your agent is not failing to choose the right tool in that case. It never saw it. This is a good reason not to treat "register everything, let the model sort it out" as a safe default. It is not safe, and it is not free.

Register for the moment, not for the whole app

The fix that actually holds up is scoping tools to where the user is and what they are doing, then taking them away again. WebMCP's model of registering tools against page state is built for exactly this: a checkout page registers apply-discount-code and select-shipping-method; navigate away and they unregister, because they are meaningless anywhere else. The same discipline applies to MCP servers that aren't tied to a page. If your agent moves through phases of a task, register the tools for the current phase and drop the tools for the phase that has finished. A drafting phase might expose save-draft and insert-citation. A review phase drops those and exposes submit-for-approval and request-changes. The model at any moment is choosing from four or five tools that are all genuinely relevant, not from thirty where twenty-five are noise from a different part of the app.

This takes more engineering than registering the full toolset once at startup. It means tracking state and wiring registration to it. That work is where the reliability gain actually lives, and it is a better investment than tuning descriptions on a bloated tool list, because a tighter list needs less tuning to begin with.

A description is a routing decision, not a label

Most tool descriptions read like documentation: what the tool does, what parameters it takes, maybe a note on the return type. That is fine for a human skimming a reference page. It is not enough for a model deciding, mid-conversation, between this tool and the one next to it in the list. A description earns its place when it tells the model when to prefer this tool over its nearest neighbour, not just what the tool does.

Compare these two for a pair of tools that both touch calendar events:

"Updates an event's fields." vs "Updates fields on an existing event identified by ID. Use this when the event already exists and only specific fields are changing. Do not use this to reschedule a recurring series; use update-recurring-event for that."

The second version is longer, but it is doing real work: it names the boundary case and points at the tool that handles it. That sentence is the one that stops the model reaching for the wrong function when a recurring event shows up. Write descriptions with the neighbouring tool in mind, not the tool in isolation.

Kill the overlap before it reaches the model

Some wrong choices are not the model's fault at all. If two tools can both plausibly satisfy the same request, you have handed the model a coin flip and called it a decision. This happens most often when tools have grown organically: send-message and notify-user both exist, do almost the same thing, and neither description explains why you would choose one over the other because nobody designed them as a pair. The fix is not a better description. It is removing the overlap: merge the tools, or narrow one so its scope genuinely excludes the other. If you cannot write a sentence explaining when a human would pick tool A over tool B, the model cannot either, and it will guess.

Name the difference between doing and starting

Naming carries more of the routing burden than it gets credit for. create-event reads as a single, complete action: give it the details, it makes the event. start-event-creation reads as the first step of something with more steps to follow, likely a form or a wizard the model needs to walk through. If your tool actually behaves like the second thing but is named like the first, the model will call it expecting a finished event and be confused by a half-open form in the response. Name for what actually happens, and keep "start" or "begin" reserved for tools that genuinely open a multi-step flow rather than complete an action in one call. A user asking to create an event and an agent calling something named for starting a workflow is a small mismatch that produces a large amount of correcting later in the conversation.