MCP Tool Descriptions That Route the Model to the Right Call

The model picks a tool from the text you gave it. A description that says "handles data" is how you get a delete call when the user asked for a count. MCP does not add judgment. It adds a list. The name, the one-paragraph description, and the JSON schema are that list.

Write the description as the condition for calling the tool, not as a marketing line.

Weak	Routes
"Account tool"	Anything with the word account
"Gets an account by id. Does not search. Does not update."	A request that already has an id
"Search accounts by name or domain. Returns at most 20 summaries, not full records."	A request that does not have an id yet

The negative sentence matters. Models call the closest tool. If search and get-by-id both say "accounts," the model flips a coin. Say what the tool will not do, and name the other tool that will.

Schema is part of the description

Required fields are instructions. If accountId is required on the get tool, the model has to produce one, which pushes it toward search first when the user typed a name. Optional fields that you did not mean to be optional will be filled with guesses. Mark required what the server actually needs. Give each property a description with the format: "GUID from search_accounts, not the account number printed on an invoice."

Enums beat free strings for status, channel, and environment. A free string becomes "prod", "production", and "PROD" in the same afternoon. The server can reject the others. It is cheaper if the schema never offers them.

Return errors as tool results the model can read: which argument was wrong, and which tool to call instead. A stack trace teaches the model nothing. "accountId is not a GUID. Call search_accounts with the name." teaches the next step. That is the same idea as keeping side effects behind a confirmation tool. A tool named delete_account should not be the first match for "how many accounts are in EMEA."

When two tools still get confused

If traces show the wrong tool more than rarely, the descriptions overlap. Merge them, or make the boundary a single word the user actually says. "Invoice" versus "payment" is a boundary. "Get data" versus "fetch data" is not.

Log the tool name, the arguments, and whether the user accepted the result. Review the misses weekly. Change the description, not the temperature. A longer system prompt that repeats the same vague tools does not fix routing. Shorter tools with sharper sentences do.

Keep the list small. Past a few dozen tools the model skims, and the descriptions you labored over are competing with noise. Group rare operations behind one tool that takes an action enum, or behind a second server the client enables only in that workflow. The routing problem is a writing problem until the catalog is too big to read. Then it is a catalog problem.