# Description says when to use the tool

**Add a sentence that says when to choose the tool, and when not to ("Use this when ... Do not use for ..."), so the model can pick between similar tools.**

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

## What fails

The description says what the tool does but not when to choose it over its siblings.

## The rule

> Description: start with “Use this when…” and call out disallowed cases (“Do not use for reminders”).

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

## How to fix it

Add a sentence such as "Use this when ... Do not use for ...".

1. Add "Use this when ..." with the user situations the tool is for.
2. Add "Do not use for ..." naming the sibling tool that covers the other case.
3. Keep it about selection, not about how the model should behave.

### 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(
  'search_issues',
  {
    title: 'Search issues',
    description: 'Search issues by text. Use this when the user describes an issue but has no ID. Do not use for a known ID; use get_issue.',
    inputSchema: z.strictObject({
      query: z.string().describe('Words to search for'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ query }) => ({ 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="Search issues",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def search_issues(
    query: Annotated[str, Field(description="Words to search for")],
) -> str:
    """Search issues by text. Use this when the user describes an issue but has no ID. Do not use for a known ID; use get_issue."""
    return "Done"
```

## Questions

### Is "Do not use for" an instruction to the model?

It is selection guidance within your own server, which both platforms accept. Steering the model away from other servers’ tools is what they reject.

### Does this help with many tools?

Yes. The more similar tools a client has loaded, the more the "when" sentence decides which one is picked.

## Related checks

- [Description says what the tool does and when to use it](https://isokron.ai/mcp-check/checks/anthropic-description)
- [Sibling tools have distinguishable descriptions](https://isokron.ai/mcp-check/checks/design-near-duplicate)
- [No steering of when other tools are used](https://isokron.ai/mcp-check/checks/sec-cross-tool-steering)
- [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: Schema and description quality.

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

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