[DOCS] Discrepancy in MCP Tool Naming Conventions (Colons vs. Double Underscores)

Documentation Type

Unclear/confusing documentation

Documentation Location

• docs/en/agents-and-tools/agent-skills/best-practices.md - docs/en/agent-sdk/mcp.md

Section/Topic

MCP (Model Context Protocol) tool naming and namespacing conventions.

Current Documentation

In Agent Skills Best Practices (best-practices.md), the documentation states:

"Format: ServerName:tool_name. Example: Use the BigQuery:bigquery_schema tool to retrieve table schemas."

In Connect to external tools with MCP (Agent SDK) (mcp.md), the documentation states:

"MCP tools follow the naming pattern mcp__<server-name>__<tool-name>. For example, a GitHub server named 'github' with a list_issues tool becomes mcp__github__list_issues."

What's Wrong or Missing?

The documentation provides two contradictory naming standards for the exact same protocol (MCP) without explaining the context in which each applies.

• The Agent SDK uses a specific namespacing convention (mcp__server__tool) to handle tool routing through its internal transport layer.
• The Direct Messages API and Agent Skills use a different convention (Server:tool).

If a developer follows the SDK documentation while trying to implement a standalone Agent Skill, or vice-versa, they will encounter "Tool Not Found" errors. There is no clarification that the mcp__ prefix is an abstraction specific to the Agent SDK library rather than the underlying Model Context Protocol or the Claude API itself.

Suggested Improvement

Add a "Note on Naming Conventions" to both the Agent SDK and the Agent Skills documentation to clarify the distinction.

Suggested Text for agent-sdk/mcp.md:

Note on Tool Naming: When using the Agent SDK, tools are automatically prefixed with mcp__ and use double underscores (e.g., mcp__github__list_issues). This is specific to the SDK's tool routing. If you are using the direct Messages API or Agent Skills, the standard format is ServerName:tool_name.

Suggested Text for agents-and-tools/agent-skills/best-practices.md:

Note on Tool Naming: For Agent Skills and direct API use, use the colon format: ServerName:tool_name. Note that this differs from the Claude Agent SDK, which uses a mcp__ prefix and double underscores.

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation:
• Agent Skills Best Practices
• Agent SDK MCP Documentation
• Examples from other projects: Most SDKs that wrap a lower-level API explicitly call out when they are applying a proprietary namespacing or "munging" to resource IDs (e.g., Kubernetes API vs. higher-level controllers). Consistent cross-referencing prevents developers from hardcoding names that only work in a specific library context.