MCP Tool Naming Conventions: Names, Titles, and Collisions

An MCP tool name is a protocol identifier, not a sentence. It is the stable handle a client uses when it lists a server's tools and sends a tools/call request. A title can make that tool readable in a user interface, while the name must remain predictable for software. Treating the two fields as the same thing creates avoidable compatibility and selection problems.

What the MCP specification says about tool names

The current MCP tools specification says that names should be one to 128 characters, should be treated as case-sensitive, and should use letters, digits, underscores, hyphens, and dots. Names should not contain spaces or commas and should be unique within a server. These are interoperability guidelines, so a server should validate its own catalog before publishing it.

• Use lowercase names when you do not have a strong reason to preserve case. Consistency lowers the chance of client-side lookup mistakes.
• Choose one separator convention, such as snake_case or dotted namespaces, and apply it to the complete catalog.
• Avoid names that differ only by case, punctuation, or an abbreviation that a model will not recognize.
• Keep a name stable after release. If the behavior changes materially, add a new versioned name and document the migration.

Name, title, and description have different jobs

The name is for machines. The optional title is for display. The description explains when the tool is useful, what it accepts, what it changes, and what it returns. A name such as search_repositories does not tell a client whether the search is fuzzy, scoped to one organization, or read-only. That meaning belongs in the description and input schema.

{
  "name": "search_repositories",
  "title": "Search repositories",
  "description": "Find repositories visible to the authenticated user. Read-only. Use the organization filter when the account has more than one organization.",
  "inputSchema": {
    "type": "object",
    "properties": { "query": { "type": "string" } },
    "required": ["query"]
  }
}

Why collisions appear in real deployments

A server can avoid duplicate names inside its own list and still encounter collisions when a host combines tools from several servers. The host owns the combined catalog, not the individual server. A client may add its own namespace, but a server should not assume that it will happen or depend on a particular host's display convention.

The practical response is to make names specific without making them unreadable. A domain prefix can help when a server exposes several subsystems, such as billing_list_invoices and billing_get_invoice. A prefix is less useful when it repeats the server name that the host already shows beside every tool. Review the final catalog in the clients your users actually run.

A catalog review that catches most naming defects

• List every name and check for duplicates, case-only differences, whitespace, punctuation, and accidental truncation.
• Read the names without the descriptions. If two tools appear interchangeable, make their scope or action more explicit.
• Check the title and description for alignment with the actual handler, authorization rule, side effects, and result shape.
• Call each tool with valid and invalid arguments. A clean name does not compensate for a misleading schema or an opaque error.
• Record the catalog version or deployment identifier so a change in selection can be compared with a known release.

What to measure after a rename

A rename changes more than a label. It can change model selection, client caches, saved prompts, allowlists, and the continuity of your analytics. If you must rename a tool, keep the old name during a deprecation window when that is safe, or publish a clear migration. Track calls by the stable name and keep the release or deployment identifier alongside them.

TrackMCP measures the server boundary: which tools are listed or called, observed duration, errors, client context, and explicit workflow signals when they are emitted. It cannot tell you every tool a host considered and rejected, so a drop in calls is evidence of changed server-boundary behavior, not a complete explanation of the model's decision.

A naming convention for a team

• Use verb_noun for actions, such as create_ticket or list_repositories.
• Use a domain prefix only when it prevents real ambiguity in the combined catalog.
• Reserve suffixes such as _preview or _v2 for behavior that is intentionally different and documented.
• Never encode secrets, tenant identifiers, or user data in a tool name.