Skip to content
IsoKron

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 ...".

  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

TypeScript
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"

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.

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