Sibling tools have distinguishable descriptions
When two tools have nearly the same description, the model cannot tell which to pick; say in each description what sets it apart from the other.
Check design-near-duplicate · Schema and description quality · default severity: attention · rubric 2.1.0
What fails
Two tools have nearly the same description (word overlap of 85% or more), so the model cannot tell when to pick which.
The rule
Each tool description should state precisely what the tool does and when to invoke it.
How to fix it
Say in each description what sets it apart from the other.
- Find pairs that differ in one word (list_issues and search_issues described the same way).
- State the difference: input (ID vs text), scope (mine vs all), output (summary vs full).
- Merge the tools if there is no real difference.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'list_my_issues',
{
title: 'List my issues',
description: 'List issues assigned to the signed-in user, newest first. Use for "my issues"; for everyone’s issues use list_issues.',
inputSchema: z.strictObject({
state: z.enum(['open', 'closed', 'all']).default('open').describe('Which issues to include'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ state }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated, Literal
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="List my issues",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def list_my_issues(
state: Annotated[Literal["open", "closed", "all"], Field(description="Which issues to include")] = "open",
) -> str:
"""List issues assigned to the signed-in user, newest first. Use for \"my issues\"; for everyone’s issues use list_issues."""
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
How does the checker measure similarity?
Word overlap between descriptions; 85% or more is flagged. Generated tools often share a template and trip it.
Should I merge similar tools?
If they differ only in a filter, one tool with that filter as an argument is usually better for the model.
Related checks
- Description says when to use the tool
- Description says what the tool does and when to use it
- Larger catalogs use a naming prefix
- 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 Anthropic connector pre-submission checklist 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