# 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. Last verified against Anthropic connector pre-submission checklist on 2026-11-18.

## 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](https://claude.com/docs/connectors/building/review-criteria#write-narrow-accurate-descriptions)

## 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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/openai-description)
- [Description says when to use the tool](https://isokron.ai/mcp-check/checks/design-use-when)
- [Sibling tools have distinguishable descriptions](https://isokron.ai/mcp-check/checks/design-near-duplicate)
- [No wording that overrides instructions or hides actions from the user](https://isokron.ai/mcp-check/checks/sec-instruction-phrases)
- [MCP tool descriptions](https://isokron.ai/mcp-check/checks/descriptions)

## Further reading

- [Why MCP tool design matters for agent reliability](https://isokron.ai/research/why-mcp-tool-design-matters)

Counts toward: Anthropic connector directory.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
