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.
How to fix it
Prefix names by service or resource, for example asana_search and asana_projects_search.
- Pick a short prefix: the service (acme_) or the resource (issues_).
- Apply it to every tool, then check the longest name still fits in 64 characters with the client prefix.
- Keep the prefix out of titles, which people read.
TypeScript SDK
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
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.
Related checks
- MCP tool name length: 1 to 128 characters
- Sibling tools have distinguishable descriptions
- Tool names that say what the tool does
- All checks in MCP tool names
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