Raise an error when duplicate tool names are registered

[koic]

Motivation and Context

This raises an exception when duplicate tool names are registered, instead of silently overwriting tools. Tool names are required to be unique within a server, so this behavior aligns with the MCP specification.

Tool names SHOULD be unique within a server.

https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-names

Validation for tool names could be made more strictly spec-compliant in a separate effort.

Fixes #197

How Has This Been Tested?

Regression and updating tests pass.

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[atesgoral]

Won't this make the default tool names overly verbose, as they're presented to the LLM? Can't developers use the existing escape hatch of defining a custom name when registering a tool?

I also don't see a single MCP server/controller exposing tools with the same names as being a common use case. If the use case is an MCP gateway, then it could be the responsibility of the gateway (acting as host AND server) to apply a convention for prefixing tool names from upstream MCP servers.

[koic]

Thank you for the well-reasoned feedback.

I do have concerns about tool names becoming longer. However, the effect applies only to default tool names when no explicit name such as tool_name: "custom name" is provided. Using a fully qualified name as the default could be seen as a clear and unambiguous representation.

As reported in #197, current default tool naming can cause tools to be unexpectedly dropped, and that outcome is concerning from a user-experience standpoint.

If a tool name that is more suitable for an LLM (or simply shorter and more concise) is preferred, it should be advisable to specify one explicitly with tool_name: "more preferable name".

There is also a possibility of providing a warning from MCP server to the LLM when a configuration such as tool_name: "duplicated name" results in duplicate names, although that would be a separate feature to consider.

[atesgoral]

How about we raise an exception when a duplicate tool name is registered? So the developer would know and override the name. Anything we do to prevent the silent ignoring of tools is better here.

[koic]

How about we raise an exception when a duplicate tool name is registered?

Yeah, this does seem like a good approach. Since "Tool names **SHOULD** be unique within a server", it should also align with the MCP specification.
https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-names

After this, I will update the PR with this approach!

[koic]

I've updated this PR to raise an error when duplicate tool names are registered.

NOTE: Validation for tool names could be made more strictly spec-compliant in a separate effort.