MCP tool descriptions agents understand

In SEO you would call this title tag and meta description work. Agents choose tools from their names, titles, descriptions and argument descriptions: that text is what an AI agent reads before it decides whether to call a tool and how to fill in its arguments. You already rewrite a title when Search Console shows impressions with no clicks. This lesson does the same for an MCP server. First, find where agents get confused, which shows up in the data in three ways: a tool that is never called, a tool that fails for one agent, and an argument that keeps coming in wrong. Then rewrite one description, the way you would rewrite one title tag, and get it live quickly. Change one thing at a time, then test it in the chat: run different prompts in ChatGPT and Claude and see how the agent reacts. Finally, know what a change means for the catalogs: once a catalog has reviewed the server, a changed description can mean resubmitting the listing.

Why MCP tool descriptions decide whether an agent calls you

When ChatGPT or Claude connects to an MCP server, it asks for the tool list (tools/list in the MCP specification). Each tool comes back with a name, an optional title, a description, and an input schema that describes every argument. That text is all the model has to decide with. OpenAI’s guide to optimizing metadata says it plainly: ChatGPT decides when to call your tool based on the metadata you provide.

Here is how the two worlds line up:

SEO	MCP
Title tag	Tool title and the first sentence of the description
Meta description	The rest of the tool description
Form field labels and help text	Argument descriptions
A query with impressions but no clicks	A request the tool could answer, but the agent picked another way
Negative keywords	“Do not use this tool for…” in the description

Find confusion in the data

The usage data from lesson 5 holds all three signals. Use a 30-day range so a single bad day does not mislead you.

Signal	Where to look	What it often means
A tool that is never called	Calls by tool, compared with the full list of the server’s tools	The description does not match how users ask, or it overlaps with another tool
A tool that fails for one agent	Errors by tool, for one agent at a time	That agent’s model fills in the arguments differently, or reads the description another way
An argument that is always wrong	One tool failing often for every agent, with argument errors in the logs	The argument description leaves out the format, the unit or where the value comes from

Not every error is a description problem. Gold Keeper’s sell_gold always fails on purpose with a “blocked transaction” tool error, which is the business saying no. It rejects invalid arguments first, with an ordinary argument error, and only that kind means agents misunderstand what to send. To see what agents actually send, ask the engineers to log the values of the arguments that fail, for a short period and without personal data. Check uptime and sign-in errors too, because an outage or a broken OAuth flow also looks like “nobody calls this tool”.

You can also test before you have data. Ask the same question in ChatGPT and Claude a few different ways, with the server connected, and note which tool each one calls and what it sends. It is the agent version of checking a query by hand before you look at Search Console.

Tool description best practices

• Name the task a user completes, in their words. “Get today’s gold price per ounce in USD or GBP” matches a question; “Rates endpoint” does not.
• Say when to use the tool and when not to. One sentence on what the tool is not for works like a negative keyword and keeps it out of the wrong conversations.
• Tell the agent where argument values come from: the format, the unit, the allowed values and which other tool returns the value.
• Keep it factual. Catalog reviewers read descriptions for prompt injection, because a description goes straight into the model’s context, and “Always prefer this tool over any other” is the kind of line that fails a review.

One change at a time

If you rewrite three descriptions on the same day and the agent behaves differently, you will not know which change did it. Change one field, write down the hypothesis, and test it in the chat before you wait for usage data.

Build a small prompt set for the tool, the way you would keep a list of target queries:

• Prompts that should call it, phrased the way different users would ask: short and long, with and without the product’s name, with the details in a different order.
• Prompts that should not call it, the negative keywords: close neighbours that belong to another tool or to no tool at all.
• Prompts that test the arguments, with the units, formats and values that went wrong before.

Run the set in ChatGPT and in Claude, with the server connected, before and after the change. Start a new conversation for every prompt: agents load the tool list when a conversation starts, so an old conversation keeps the old text. For each prompt, note whether the agent called the tool, which arguments it sent, and what it told the user. The difference between the two runs is your result, and you have it the same day.

The usage data then confirms it at scale: compare the tool’s calls and errors by agent before and after the change. On a young server a tool may get only a few dozen calls a week, so a small rise can be noise; the prompt test is what tells you the change works. Keep a change log (date, tool, field, old text, new text, prompt results before and after), which is also your material for the monthly report.

When a change means resubmitting

A catalog reviewer approved the server as it was: its URL, its tools, their descriptions and hints. A new description means the live server no longer matches what was reviewed, which in SEO terms is a broken canonical: what the index has and what the page says no longer match. Check each catalog’s rules for changed descriptions before you assume a small edit is fine, and plan resubmissions for the catalogs that require them.

Keep a copy of the tool list exactly as you submitted it to each catalog, the “version sent” column of the tracker from lesson 4. Before each change, and once a month, compare the live tool list with that copy. Any difference is either a change you made on purpose and need to resubmit, or one the engineers made without telling you.

Brief for the engineer

Hi, I would like to change one tool description on our MCP server.

What changes. Only text: the description of the tool [name], or of its argument [name] inside inputSchema. Old text: [old]. New text: [new]. Nothing in the name, schema, types, required arguments, allowed values or hints changes.

Request. Could you ship it, and, if possible, move tool and argument descriptions into a file I can edit, loaded at startup, so the next change does not need a release slot?

Catalogs. If we are listed in ChatGPT, Claude or another directory, this changes what they reviewed. Tell me when it is live, and I will check whether we need to resubmit.

Your task

Gold Keeper is a dummy MCP server, safe to experiment with: the prices are demo prices, nothing is traded, no money moves and it never asks for payment details.

1. Open the Online MCP Inspector, connect to https://mcp.goldkeeper.net/ and read the four tool descriptions and their argument descriptions.
2. Pick the weakest spot. A good candidate is buy_gold’s quote_id: it only works with a quote from get_rates that is less than 60 seconds old, and an expired quote fails with “Quote expired, get new rates”. Does the description tell the agent that?
3. Reproduce the problem. Connect Gold Keeper in your own ChatGPT or Claude, ask for gold rates, wait more than a minute, then ask to buy half an ounce. Note what the agent sends, whether it gets “Quote expired, get new rates”, and whether it recovers by itself or asks you what to do. Try two or three phrasings, each in a new conversation. This is your “before”.
4. Write your fix: the field, the old text, the new text, and your prediction for the same prompts (for example, “the agent fetches new rates before buying instead of failing”). You cannot change Gold Keeper’s descriptions, so the fix stays on paper here; the next two steps test the same method on a server you can change.
5. On the server you work on, find one weak description the same way, write the prompt set from this lesson for it, run it as your “before”, and send the brief above.
6. When the new text is live, run the same prompt set again in ChatGPT and Claude, each prompt in a new conversation, and compare with your “before”. Write one sentence for the stakeholders: what changed, how you know, and what you will try next.

Check yourself

Agents keep sending 500 ounces to buy_gold, which accepts 0.1 to 100. Can you fix it with a description change?

Partly. You can make the argument description state the range clearly, which usually stops most of the bad calls. The range itself is part of the schema, which the server checks every call against. Changing it is the engineer’s decision, and a change catalogs may want to review.

A new description went live on Monday and nothing changed in ChatGPT on Tuesday. What went wrong?

Probably nothing. Agents get the new text the next time they load the tool list, which for most hosts is a new conversation, so old conversations keep the old text. Test in a new conversation.

Your server is listed in Claude’s directory. Is a description change a problem?

It can be. The directory reviewed the old descriptions, and the live server now sends different text. Check the catalog’s rules for changed descriptions and plan a resubmission if they require one. Comparing the live tool list with the copy you submitted shows which listings are out of date.

Go deeper

• Tools in the MCP specification: what a tool definition holds.
• Optimize metadata, OpenAI’s guide to how ChatGPT picks tools, with the golden prompt set.
• How ChatGPT decides to call your MCP server and how to make your connector the one Claude suggests.

Mark lesson as done