# 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. Last verified against Anthropic connector pre-submission checklist on 2026-11-18.

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

Source: [Anthropic connector pre-submission checklist](https://claude.com/docs/connectors/building/review-criteria#write-narrow-accurate-descriptions)

## How to fix it

Say in each description what sets it apart from the other.

1. Find pairs that differ in one word (list_issues and search_issues described the same way).
2. State the difference: input (ID vs text), scope (mine vs all), output (summary vs full).
3. Merge the tools if there is no real difference.

### 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_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

```python
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"
```

## 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](https://isokron.ai/mcp-check/checks/design-use-when)
- [Description says what the tool does and when to use it](https://isokron.ai/mcp-check/checks/anthropic-description)
- [Larger catalogs use a naming prefix](https://isokron.ai/mcp-check/checks/design-namespace)
- [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
