Your MCP Server Is Only as Good as Its Tool Descriptions

An MCP tool is not useful because it exists.

It is useful when the agent understands when, why, and how to call it.

That means tool descriptions matter more than people think.

If the description is vague, the agent guesses.

If the input schema is unclear, the agent passes messy arguments.

If two tools overlap too much, the agent may choose the wrong one.

The tool might work perfectly at the code level and still fail at the agent level because the model does not understand its purpose.

The hidden interface

When people think about MCP servers, they often focus on implementation:

• connect to data
• expose tools
• return results
• test the transport

That is important.

But the tool description is the hidden interface between your server and the model.

Humans read documentation.

Agents read tool descriptions.

If the description is weak, your MCP server becomes harder for the agent to use reliably.

A bad tool description

Imagine this tool:

get_projects

Bad description:

Gets projects.

That is technically true and practically weak.

The agent does not know:

• what kind of projects
• whether archived projects are included
• whether it can filter
• what fields come back
• when to use this tool instead of another one

The description is too thin to guide behavior.

A better tool description

Better description:

Returns projects from Orlando Ascanio's personal hub. Use this when the user asks what Orlando has built, asks for projects by technology or tag, or needs examples of his work. Supports optional tag, status, and locale filters.

That gives the agent decision context.

It explains:

• whose projects
• when to call the tool
• what user intents it matches
• what filters exist

That is much more useful than "Gets projects."

Tool descriptions should answer four questions

A good MCP tool description should answer:

1. What does this tool return or do?
2. When should the agent use it?
3. What inputs matter?
4. What should the agent not assume?

For example:

Returns a single product from Orlando's personal hub by slug. Use after get_products when the user asks for more detail about a specific product. Requires an exact product slug. Returns not found if the slug does not exist.

That description helps the agent sequence tools correctly.

It nudges the agent to call get_products first if it does not know the slug.

Input schemas are part of the description

The schema is not just validation.

It is guidance.

This is vague:

query: string

This is clearer:

topic: optional string used to filter notes by title, category, excerpt, or content. Examples: "AI agents", "Chrome extensions", "product thinking".

The model needs to know what kind of text belongs in the field.

Is it a search query?

Is it an exact enum?

Is it a slug?

Is it a natural-language topic?

Those details change the argument the model will send.

Use enums when the choice is finite

If a field only accepts known values, make that explicit.

For example:

status: "active" | "archive"

This is better than:

status: string

Enums prevent the model from inventing values like:

• published
• done
• live
• completed

Those might be reasonable words, but they are not valid inputs.

Agent reliability improves when the schema removes unnecessary freedom.

Split tools when intent is different

One common mistake is building one giant tool that does everything.

For example:

search_everything

It might search projects, products, notes, profile information, status, links, and content.

That sounds convenient, but it creates ambiguity.

Sometimes a broad search tool is useful. But if the common user intents are distinct, separate tools are usually cleaner:

get_projects
get_project
get_products
get_product
get_notes
get_note
get_orlando_bio

Each tool has a narrower purpose.

The model has an easier choice.

The result is easier to interpret.

Avoid overlapping tool names

Overlapping names make agents uncertain.

For example:

get_work
get_projects
get_products
get_all_items

If all four return similar things, the agent may choose inconsistently.

Better:

• get_projects for project case studies
• get_products for shipped products
• get_notes for writing
• get_orlando_bio for profile context

The names should encode the content model.

Include boundaries in the description

Tool descriptions should also explain limits.

For a personal hub MCP server, a useful boundary might be:

This tool only returns public content from the site. It does not access private drafts, analytics, billing data, or admin records.

This helps the agent avoid implying it has access to things it does not.

It also helps users understand the safety model.

Return summaries when possible

Tool descriptions guide the call.

Tool results guide the answer.

That is why I like including ai_summary in API responses and text summaries in MCP results.

Agents can parse raw JSON, but a short explanation reduces ambiguity.

For example:

Found 5 notes about AI engineering. These notes cover prompt engineering, agent architecture, and production reliability.

That gives the model context before it synthesizes an answer.

The best MCP tools feel obvious

A good MCP tool should feel obvious to the model.

The user asks:

What has Orlando shipped?

The agent sees:

get_products - Returns Orlando's shipped products...

The choice should be easy.

If the agent has to reason too hard about which tool to call, the tool surface probably needs better names, clearer descriptions, or narrower responsibilities.

The rule I follow

Every MCP tool should have:

• a specific name
• a clear description
• narrow responsibility
• typed inputs
• finite enums when possible
• explicit boundaries
• predictable result shape

The implementation matters.

But the description is what lets the agent discover the implementation in the first place.

Your MCP server is only as good as its tool descriptions.