# Every argument has a description

**Give every argument a description that says what it is and its format, with an example where the format matters; without one the model guesses from the name.**

Check `schema-param-description` · Schema and description quality · default severity: advice · rubric 2.1.0. Last verified against OpenAI: Optimize metadata on 2026-11-18.

## What fails

Without a description the model guesses an argument's meaning and format from its name.

## The rule

> Parameter docs: describe each argument, include examples, and use allowed values for constrained inputs.

Source: [OpenAI: Optimize metadata](https://developers.openai.com/plugins/guides/optimize-metadata)

## How to fix it

Add a "description" to each argument, with an example value where the format matters.

1. Add a "description" to each property.
2. Include the format and an example for IDs, dates and codes ("Issue ID, for example ISS-42").
3. State units and defaults ("Maximum results, 1 to 100, default 20").

### 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(
  'list_events',
  {
    title: 'List events',
    description: 'List calendar events in a date range. Use when the user asks what is scheduled.',
    inputSchema: z.strictObject({
      start_date: z.string().describe('First day to include, YYYY-MM-DD, for example 2026-11-18'),
      end_date: z.string().describe('Last day to include, YYYY-MM-DD'),
      limit: z.number().int().min(1).max(100).default(25).describe('Maximum events, 1 to 100'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ start_date, end_date, limit }) => ({ 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="List events",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def list_events(
    start_date: Annotated[str, Field(description="First day to include, YYYY-MM-DD, for example 2026-11-18")],
    end_date: Annotated[str, Field(description="Last day to include, YYYY-MM-DD")],
    limit: Annotated[int, Field(description="Maximum events, 1 to 100", ge=1, le=100)] = 25,
) -> str:
    """List calendar events in a date range. Use when the user asks what is scheduled."""
    return "Done"
```

## Questions

### Where do argument descriptions go in the SDKs?

TypeScript: .describe("...") on each zod field. Python: Annotated[str, Field(description="...")] on each parameter. Both end up as "description" in the JSON Schema.

### Do descriptions on arguments count toward review?

OpenAI’s metadata guide asks for them; neither directory rejects a tool for missing argument docs alone, but models call such tools wrongly more often.

## Related checks

- [Constrained arguments list their allowed values](https://isokron.ai/mcp-check/checks/schema-enum-missing)
- [Argument names are specific](https://isokron.ai/mcp-check/checks/schema-vague-param)
- [Description says what the tool does and when to use it](https://isokron.ai/mcp-check/checks/anthropic-description)
- [MCP tool descriptions](https://isokron.ai/mcp-check/checks/descriptions)

Counts toward: Schema and description quality.

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

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