How do you write MCP tool descriptions an agent actually uses correctly?

You write a tool description an agent uses correctly by stating, in plain sentences, which questions the tool answers, which it does not, and what comes back when it has nothing to say. The agent never sees your code or your intentions. It sees a name, an input schema and a description, and it decides from those whether to call the tool. Whatever the description leaves out, the agent fills in by guessing.

This article is about the wording of each entry. For the choice of which tools to publish in the first place, see what to expose when you build an MCP server on your own SaaS. For why the description is the decision point, see why an agent invents product features.

One entry, four passes

The easiest way to see what a description does is to rewrite one. The tool below belongs to a fictional SaaS and the example is illustrative. It looks up the state of an order.

Pass 0, the draft most catalogs ship.

get_order_status: Gets order status.

It is accurate and it is useless. An agent asked "where is my parcel?" may call it. Asked "why was I charged twice?", it may call it too, because nothing says it should not. The description describes the function. It says nothing about the question.

Pass 1, name the question.

Returns the current status of one order (placed, paid, shipped, delivered, cancelled). Use it when someone asks where an order is or whether it has shipped.

Now the model has a trigger. Notice what changed: the sentence starts from what the person asks, not from what the function does. Two examples of phrasing, "where is my order" and "has it shipped", would help further.

Pass 2, draw the border.

… Does not explain charges, refunds or invoices: use get_billing_history for those. Does not return delivery estimates.

This is the pass most teams skip, and the one that prevents the most wrong calls. A description that only says what a tool does invites the model to stretch it. A sentence about what the tool does not do, with a pointer to the neighbour that does, turns two overlapping tools into two distinct ones.

Pass 3, say what silence looks like.

… Requires an order number. If none is found, returns found: false with no other field, which means the order does not exist or the caller cannot see it. Do not guess a number.

Without this, an agent that gets an empty answer has no instruction. Some will retry with an invented identifier; some will state that the order does not exist when the truth is that the caller has no access. A description that names the empty result gives the agent something true to say.

The final entry, in full.

Returns the current status of one order (placed, paid, shipped, delivered, cancelled). Use it when someone asks where an order is or whether it has shipped, for example "where is order 4821?". Does not explain charges, refunds or invoices (use get_billing_history) and does not return delivery estimates. Requires an order number; never guess one. If nothing is found it returns found: false, which means the order does not exist or the caller cannot see it.

Four sentences. Each one removes a failure the draft allowed.

The five things a description should carry

The rewrite above follows a pattern you can apply to any entry.

1. The question, in the user's words. Start from what someone asks, not from the function signature.
2. The border. What the tool does not handle, and which tool does.
3. The input it needs. If the call fails without an identifier, say so, and say not to invent one.
4. The empty result. What comes back when there is nothing, and what that means.
5. The scope of the answer. What is covered: all customers, one project, the last 90 days. A tool that silently covers less than the question implies produces confident wrong answers.

A sixth point applies when a tool changes anything: say so in the first sentence. Read-only and read-write tools should not be distinguishable only by their names.

What to leave out

Short descriptions have an advantage that is easy to underrate: there is less in them to go stale. Leave out internal vocabulary the caller has never heard, implementation notes ("queries the replica"), and anything that will change next quarter. If a limit moves often, say "see the response for the current limit" and put the figure in the response.

Avoid marketing sentences too. "Powerful, flexible search across your product" adds words and no routing information.

Testing a description without a live agent

You do not need a deployed agent to find weak entries. Write twenty questions: ten the tool should handle, ten it should not, including a few from neighbouring tools. Give a model the full catalog, descriptions only, and ask which tool it would call for each question, or whether it would call none.

The mismatches are the fix list. A question that should have matched and did not points at a missing trigger (pass 1). A question that matched and should not have points at a missing border (pass 2). A call with an invented identifier points at pass 3. Re-run after each edit; it takes minutes.

"Won't the model figure it out anyway?"

For a catalog of three clearly distinct tools, often yes. The trouble starts when tools overlap, when two of them can plausibly answer the same question, or when the right answer is "none of them". That is the case where the description decides, because the model has nothing else to go on.

DeployIt is a different kind of thing from the catalog above: it does not act inside your product, it answers questions about it. It reads the real code (resynced on every push) and the git history (commits and diffs), and checks the code before asserting anything. The connection is read-only and revocable at any time, one MCP server per project. If you maintain your own catalog, these descriptions are yours to keep honest. If what you want is answers to "what changed this week?", see asking your product what changed.

Where to start

Pick the tool your agents call most. Rewrite its description in the four passes, run the twenty-question test, and keep the result as the template for the rest of the catalog. Review the descriptions again whenever a tool's behavior changes, as part of the same diff.

DeployIt's MCP server is in early access / design partner program, and the program is open. DeployIt is free during early access; paid plans arrive in January 2027.