Design MCP Tool Descriptions as UI for AI Agents

In an MCP server, a tool description is not just documentation.

For a human user interface, button labels, helper text, and error messages shape how people use the system. In MCP, tool names, descriptions, argument schemas, and error messages play a similar role for AI agents.

The model reads them to decide which tool to call and what arguments to pass. Treat them as UI for the AI agent.

Short descriptions cause misuse

This is too vague:

{
  "name": "search",
  "description": "Search articles"
}

It does not say what is searched, whether body text is included, whether tags are included, which language is searched, or whether the response includes full article bodies.

A better description front-loads the important behavior:

{
  "name": "search_articles",
  "description": "Search published Markdown articles by title, description, tags, and body text. Returns metadata only, not full article bodies."
}

Now the model knows when to use this tool and when to follow up with a detail tool.

Say when to use the tool

Tools should explain their use case, not only their capability.

Weak:

Retrieve an article.

Better:

Retrieve a single published article by slug when the caller already knows the slug. Use search_articles first when the slug is unknown.

The second version teaches the agent the intended workflow. It prevents repeated calls to get_article with guessed slugs.

Put constraints in argument descriptions

Argument schemas should include examples and forbidden formats.

Weak:

{
  "slug": {
    "type": "string",
    "description": "Article slug"
  }
}

Better:

{
  "slug": {
    "type": "string",
    "description": "Lowercase article slug such as 'mcp-stdio-server-logging-stderr'. Do not include '/articles/' or a trailing slash."
  }
}

This prevents a common mistake: passing a full URL path where the server expects only the slug.

For language fields, combine enum with plain-language guidance:

{
  "lang": {
    "type": "string",
    "enum": ["en", "ja"],
    "description": "Article language. Use 'ja' for Japanese articles and 'en' for English articles. Defaults to 'en'."
  }
}

The enum enforces valid values. The description helps the model map a user request to the right value.

Explain response size

AI clients have limited context. A tool that returns every article body can quickly overwhelm the conversation.

For the broader architecture of serving Markdown through MCP, see Designing an MCP Markdown Knowledge Server: Why It Should Not Return HTML. This article focuses only on tool descriptions and argument design.

If a tool returns metadata only, say so:

Returns an array of article metadata: slug, title, date, description, tags, and lang. Does not return article body Markdown.

If a tool returns the full body, say when to use it:

Returns metadata and the full raw Markdown body for one article. Use only after narrowing to a specific slug.

This helps the model choose list/search tools before expensive detail tools.

If the tool is implemented over stdio transport, also keep tool responses separate from diagnostic logs. See MCP stdio Server Logging: Keep Logs on stderr, Not stdout for that transport-level concern.

Error messages are part of the interface

An error like this is not useful:

Not found

Use a recoverable error:

Error: article "foo" with lang "ja" was not found. Use list_articles or search_articles to find a valid slug.

The agent can now recover without guessing.

Checklist

When adding an MCP tool, check:

• the tool name is verb + resource
• the description says what is searched, returned, or changed
• the description says when to use the tool
• argument descriptions include examples and forbidden formats
• enum and required fields express hard constraints
• metadata and full-body tools are separated
• error messages include the next recovery action

Summary

MCP tool descriptions are an interface for AI agents.

Short descriptions may work in simple demos, but they fail as tool count grows. Describe use cases, argument formats, return size, and recovery steps. The quality of the tool definition directly affects whether the model calls the right tool with the right arguments.