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.
How to fix it
Write one or two sentences: what the tool does, what it returns, and when to call it.
- Write one or two sentences: what it does and returns, then "Use when ...".
- Add what it does not do if a sibling tool covers that.
- Describe behavior, not instructions to the model.
TypeScript SDK
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
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.
Related checks
- Every tool has a non-empty description
- Description says when to use the tool
- Sibling tools have distinguishable descriptions
- No wording that overrides instructions or hides actions from the user
- All checks in MCP tool descriptions
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