Skip to content
IsoKron

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

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

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

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

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

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.

Further reading

How this check is graded

It counts toward: Schema and description quality. See the rubric.

Last verified against Anthropic: Writing effective tools for agents 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