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
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.
How to fix it
Describe the purpose, behavior, when to use it, and limitations or side effects.
- Add a description to every tool, including internal or rarely used ones.
- Cover purpose, behavior, when to use it, and side effects or limits.
- Keep claims accurate: reviewers test the tool against its description.
TypeScript SDK
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
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"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
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
- Write tools say whether a retry repeats the effect
- Description says when to use the tool
- All checks in MCP tool descriptions
How this check is graded
It counts toward: OpenAI plugin directory. See the rubric.
Last verified against OpenAI plugin guidelines, section 6.1 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