Skip to content
IsoKron

Description says what the tool does and when to use it

Each tool description should state precisely what the tool does and when to invoke it; a missing description blocks Anthropic review, and one under about 40 characters rarely covers both.

Check anthropic-description · Anthropic connector directory · default severity: blocking (or attention, depending on the case) · rubric 2.1.0

What fails

A missing description is blocking. A very short one (under 40 characters) rarely says both what the tool does and when to call it, and is marked for attention.

The rule

Each tool description should state precisely what the tool does and when to invoke it.

Source: Anthropic connector pre-submission checklist

How to fix it

Write one or two sentences: what the tool does, what it returns, and when to call it.

  1. Write one or two sentences: what it does and returns, then "Use when ...".
  2. Add what it does not do if a sibling tool covers that.
  3. Describe behavior, not instructions to the model.

TypeScript SDK

TypeScript
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';

const server = new McpServer({ name: 'issues', version: '1.0.0' });

server.registerTool(
  'get_invoice',
  {
    title: 'Get invoice',
    description: 'Return one invoice with its line items, totals and payment status. Use when the user asks about a specific invoice by number; for lists use list_invoices.',
    inputSchema: z.strictObject({
      invoice_id: z.string().describe('Invoice number, for example INV-2041'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ invoice_id }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);

Python SDK

Python
from typing import Annotated

from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

server = MCPServer("issues")

@server.tool(
    title="Get invoice",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def get_invoice(
    invoice_id: Annotated[str, Field(description="Invoice number, for example INV-2041")],
) -> str:
    """Return one invoice with its line items, totals and payment status. Use when the user asks about a specific invoice by number; for lists use list_invoices."""
    return "Done"

Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.

Questions

How long should an MCP tool description be?

Long enough for what and when: usually one to three sentences. The specification sets no limit, but every word is sent to the model on every request, so long descriptions cost context.

Can the description tell the model how to behave?

No. Anthropic rejects descriptions that tell Claude how to behave or interfere with other tools; describe the tool only.

Further reading

How this check is graded

It counts toward: Anthropic connector directory. See the rubric.

Last verified against Anthropic connector pre-submission checklist on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.

Check your tool list: paste your tools/list, nothing is sent anywhere