# Larger catalogs use a naming prefix

**Once a server has ten or more tools, prefix their names by service or resource (for example asana_search, asana_projects_search) so a model can tell them from similar tools of other servers.**

Check `design-namespace` · Schema and description quality · default severity: advice · rubric 2.1.0. Last verified against Anthropic: Writing effective tools for agents on 2026-11-18.

## What fails

The catalog has 10 or more tools and no shared service or resource word in their names, so they are easy to confuse with other servers' tools.

## The rule

> Namespacing (grouping related tools under common prefixes) can help delineate boundaries between lots of tools; MCP clients sometimes do this by default.

Source: [Anthropic: Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)

## How to fix it

Prefix names by service or resource, for example asana_search and asana_projects_search.

1. Pick a short prefix: the service (acme_) or the resource (issues_).
2. Apply it to every tool, then check the longest name still fits in 64 characters with the client prefix.
3. Keep the prefix out of titles, which people read.

### 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(
  'acme_issues_search',
  {
    title: 'Search issues',
    description: 'Search Acme issues by text. Use when the user describes an issue but has no ID.',
    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 acme_issues_search(
    query: Annotated[str, Field(description="Words to search for")],
) -> str:
    """Search Acme issues by text. Use when the user describes an issue but has no ID."""
    return "Done"
```

## Questions

### Do clients not namespace tools already?

Some do, by prefixing the server name. The model still sees search next to search from another server; a prefix in the name itself carries into every client.

### How many tools are too many?

There is no fixed number, but selection accuracy drops as similar tools pile up. Namespacing, distinct descriptions and fewer, broader tools all help.

## Related checks

- [MCP tool name length: 1 to 128 characters](https://isokron.ai/mcp-check/checks/spec-name-length)
- [Sibling tools have distinguishable descriptions](https://isokron.ai/mcp-check/checks/design-near-duplicate)
- [Tool names that say what the tool does](https://isokron.ai/mcp-check/checks/openai-name-opaque)
- [MCP tool names](https://isokron.ai/mcp-check/checks/names)

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