# Every tool has a non-empty description

**OpenAI requires every tool to have a non-empty description that explains its purpose and behavior, when to use it, and any limitations or side effects.**

Check `openai-description` · OpenAI plugin directory · default severity: blocking · rubric 2.1.0. Last verified against OpenAI plugin guidelines, section 6.1 on 2026-11-18.

## What fails

A tool with no description gives the model nothing to choose it by, and reviewers reject it.

## The rule

> Each tool must have a nonempty description that explicitly and accurately explains its purpose and behavior, when to use it, and any relevant limitations or side effects.

Source: [OpenAI plugin guidelines, section 6.1](https://developers.openai.com/plugins/plugin-guidelines)

## How to fix it

Describe the purpose, behavior, when to use it, and limitations or side effects.

1. Add a description to every tool, including internal or rarely used ones.
2. Cover purpose, behavior, when to use it, and side effects or limits.
3. Keep claims accurate: reviewers test the tool against its description.

### 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(
  'send_invoice',
  {
    title: 'Send invoice',
    description: 'Email one invoice to the customer’s billing address. Use when the user asks to send or resend an invoice. Sends a real email; a repeat call sends it again.',
    inputSchema: z.strictObject({
      invoice_id: z.string().describe('Invoice number, for example INV-2041'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
  },
  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="Send invoice",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=True),
)
def send_invoice(
    invoice_id: Annotated[str, Field(description="Invoice number, for example INV-2041")],
) -> str:
    """Email one invoice to the customer’s billing address. Use when the user asks to send or resend an invoice. Sends a real email; a repeat call sends it again."""
    return "Done"
```

## Questions

### Does a docstring count as a description?

Yes. Both Python SDKs use the function docstring as the description when none is passed.

### What side effects should I mention?

Anything the user would want to know before the call: emails sent, money charged, data shared, records changed, and whether a retry repeats it.

## Related checks

- [Description says what the tool does and when to use it](https://isokron.ai/mcp-check/checks/anthropic-description)
- [Write tools say whether a retry repeats the effect](https://isokron.ai/mcp-check/checks/openai-retry)
- [Description says when to use the tool](https://isokron.ai/mcp-check/checks/design-use-when)
- [MCP tool descriptions](https://isokron.ai/mcp-check/checks/descriptions)

Counts toward: OpenAI plugin directory.

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

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