SEP-986: Specify Format for Tool Names

[kentcdodds]

SEP-986: Specify Format for Tool Names

Preamble

• Title: Specify Format for Tool Names
• Author: kentcdodds
• Status: proposal

---

Abstract

The Model Context Protocol (MCP) currently lacks a standardized format for tool names, resulting in inconsistencies and confusion for both implementers and users. This SEP proposes a clear, flexible standard for tool names: tool names should be 1–64 characters, case-sensitive, and may include alphanumeric characters, underscores (_), dashes (-), dots (.), and forward slashes (/). This aims to maximize compatibility, clarity, and interoperability across MCP implementations while accommodating a wide range of naming conventions.

Motivation

Without a prescribed format for tool names, MCP implementations have adopted a variety of naming conventions, including different separators, casing, and character sets. This inconsistency can lead to confusion, errors in tool invocation, and difficulties in documentation and automation. Standardizing the allowed characters and length will:

• Make tool names predictable and interoperable across clients.
• Allow for hierarchical and namespaced tool names (e.g., using / and .).
• Support both human-readable and machine-generated names.
• Avoid unnecessary restrictions that could block valid use cases.

Rationale

Community discussion highlighted the need for flexibility in tool naming. While some conventions (like lower-kebab-case) are common, many tools and clients use uppercase, underscores, dots, and slashes for namespacing or clarity. The proposed pattern—allowing a-z, A-Z, 0-9, _, -, ., and /—is based on patterns used in major clients (e.g., VS Code, Claude) and aligns with common conventions in programming and APIs. Restricting spaces and commas avoids parsing issues and ambiguity. The length limit (1–64) is generous enough for most use cases but prevents abuse.

Specification

• Tool names SHOULD be between 1 and 64 characters in length (inclusive).
• Tool names are case-sensitive.
• Allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits
  (0-9), underscore (_), dash (-), dot (.), and forward slash (/).
• Tool names SHOULD NOT contain spaces, commas, or other special characters.
• Tool names SHOULD be unique within their namespace.
• Example valid tool names:
  • getUser
  • user-profile/update
  • DATA_EXPORT_v2
  • admin.tools.list

Backwards Compatibility

This change is not backwards compatible for existing tools that use disallowed characters or exceed the new length limits. To minimize disruption:

• Existing non-conforming tool names SHOULD be supported as aliases for at least one major version, with a deprecation warning.
• Tool authors SHOULD update their documentation and code to use the new format.
• A migration guide SHOULD be provided to assist implementers in updating their tool names.

Reference Implementation

A reference implementation can be provided by updating the MCP core library to enforce the new tool name validation rules at registration time. Existing tools can be updated to provide aliases for their new conforming names, with warnings for deprecated formats. Example code and migration scripts can be included in the MCP repository.

Security Implications

None. Standardizing tool name format does not introduce new security risks.

[hesreallyhim]

@kentcdodds what's the motivation for case-sensitivity? i mean, i can see a reason for it from one POV, but it seems like the only reason I can think of to have distinct case-insensitive-but-otherwise equal names would be to confuse or trick the model or the user... I guess this also relates to the status of the "title" vs the "name", but I don't want to go too far in my questioning, would just like to know more the thinking around it

[hesreallyhim]

separate comment:

Existing non-conforming tool names SHOULD be supported as aliases for at least one major version, with a deprecation warning.

Given that there previously has been NO imperative language about tool names, this is actually imposing additional requirements on clients that don't currently support e.g. 128 characters, or any non-ASCII character in fact - basically saying that they have to (on my reading of SHOULD, which is very strong), but just until the following major release. I would recommend changing the "SHOULD"s in the Backwards Compatibility Part to "should"s. But again, maybe I have a stricter reading of SHOULD than others.

[evalstate]

I can see the benefits of this proposal for Developers for general neatness, although this isn't an inherent limitation of downstream LLM chat templates. I also echo @hesreallyhim about not restricting this to latin characters. Are there other good variable naming patterns we should explore here?

I do think we should start some kind of Host integrators guide discussing common patterns.

For example one common issues integrators face is seeing a late runtime exception from their LLM Provider API (OpenAI Completions API function name check of '^[a-zA-Z0-9_-]{1,64}$'"} is common). With this proposal, after namespacing etc. names from MCP Servers will generally still need manipulation before being used.

[alexhancock]

Hi @kentcdodds

I like the proposal and have picked it up to sponsor it.

A question for you: how would you feel about this being included in the spec as a "SHOULD"? I heard concern from the core maintainers (from whom we will seek approval) that the backwards compatibility breakage if it's a "MUST" is likely already too painful to accept.

I could see us proposing it as "SHOULD", having sdks warn when a server doesn't comply, then perhaps evolving the spec towards "MUST" if adherence is good enough in the ecosystem. What do you think?

[kentcdodds]

I'm fine with that 👍