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
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
How to fix it
Add a sentence such as "Use this when ... Do not use for ...".
- Add "Use this when ..." with the user situations the tool is for.
- Add "Do not use for ..." naming the sibling tool that covers the other case.
- Keep it about selection, not about how the model should behave.
TypeScript SDK
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
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"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
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
- Sibling tools have distinguishable descriptions
- No steering of when other tools are used
- All checks in MCP tool descriptions
Further reading
How this check is graded
It counts toward: Schema and description quality. See the rubric.
Last verified against OpenAI: Optimize metadata 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