fix(core): ensure subagents use qualified MCP tool names

[abhipatel12]

Summary

This PR resolves a critical initialization crash in the generalist subagent and other dynamically configured agents when Model Context Protocol (MCP) tools are active.

Details

The issue was caused by a mismatch between the ToolRegistry and the LocalAgentExecutor:

• The ToolRegistry often exposes MCP tools using "short" aliases (e.g., get_logs) for user convenience.
• The LocalAgentExecutor enforces a strict requirement for fully qualified names (e.g., Server__get_logs) in subagents to ensure safety and prevent tool name collisions.

When the generalist agent attempted to gather all available tools, it received short aliases from the registry, which then triggered a validation error in the executor.

Changes:

• Updated ToolRegistry.getAllToolNames() and getFunctionDeclarations() to consistently use fully qualified names for MCP tools.
• Implemented deduplication in the registry to ensure tools are only presented once.
• Enhanced LocalAgentExecutor to automatically resolve and "upgrade" short MCP aliases to their qualified forms during subagent initialization.
• Added comprehensive unit tests to tool-registry.test.ts and local-executor.test.ts to verify the new qualification and resolution logic.

Related Issues

Fixes the subagent crash reported during internal testing.

How to Validate

1. Start a session with an active MCP server (e.g., Google Workspace).
2. Run a command that dispatches the generalist subagent: Can you try dispatching a generalist sub-agent to check my email?
3. Verify the agent initializes and runs without the "must be requested with its server prefix" error.
4. Run unit tests: npm test -w @google/gemini-cli-core -- src/tools/tool-registry.test.ts src/agents/local-executor.test.ts

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical bug that caused subagents to crash when attempting to use Model Context Protocol (MCP) tools. The core issue stemmed from an inconsistency in how MCP tool names were handled: the ToolRegistry often provided abbreviated names, while the LocalAgentExecutor strictly required fully qualified names. The changes ensure that MCP tools are consistently identified and processed using their fully qualified names across the system, thereby stabilizing subagent initialization and improving the reliability of tool interactions.

Highlights

• Critical Crash Fix: Resolved a critical initialization crash affecting the generalist subagent and other dynamically configured agents when Model Context Protocol (MCP) tools were active.
• MCP Tool Name Qualification: Updated ToolRegistry.getAllToolNames() and getFunctionDeclarations() to consistently return fully qualified names for MCP tools, addressing a mismatch where the LocalAgentExecutor expected qualified names while the ToolRegistry often provided short aliases.
• Automatic Alias Resolution: Enhanced LocalAgentExecutor to automatically resolve and 'upgrade' short MCP aliases to their fully qualified forms during subagent initialization, preventing validation errors.
• Tool Deduplication: Implemented deduplication logic within the ToolRegistry to ensure that MCP tools are presented only once, even if registered with both short and qualified names.
• Comprehensive Testing: Added comprehensive unit tests to tool-registry.test.ts and local-executor.test.ts to verify the new qualification and resolution logic.

Changelog

• packages/core/src/agents/local-executor.test.ts
  • Updated test description to reflect automatic qualification of MCP tools instead of strict enforcement.
  • Modified test assertions to verify that unqualified MCP tool names are now automatically upgraded to qualified names during agent definition processing.
• packages/core/src/agents/local-executor.ts
  • Removed the direct import of MCP_QUALIFIED_NAME_SEPARATOR as the explicit validation for qualified names is no longer needed.
  • Modified the tool registration logic to automatically qualify DiscoveredMCPTool instances before registering them with the agent's isolated registry, removing the previous error-throwing mechanism for unqualified names.
• packages/core/src/tools/tool-registry.test.ts
  • Updated getAllToolNames tests to assert that MCP tools are returned with their fully qualified names.
  • Added a new test case for getAllToolNames to verify the deduplication of MCP tool names.
  • Added new getFunctionDeclarations tests to ensure MCP tools use fully qualified names and are deduplicated in function declarations.
• packages/core/src/tools/tool-registry.ts
  • Modified getFunctionDeclarations to use fully qualified names for DiscoveredMCPTool instances and to deduplicate declarations based on these qualified names.
  • Updated getAllToolNames to return fully qualified names for DiscoveredMCPTool instances and to deduplicate the list of names.
  • Enhanced getAllTools to deduplicate tool instances based on their qualified names for DiscoveredMCPTools, ensuring each unique qualified tool is listed only once.

Activity

• Identified and fixed a critical initialization crash in subagents when MCP tools were active.
• Added comprehensive unit tests for tool-registry.test.ts and local-executor.test.ts to validate the new qualification and resolution logic.
• Validated the changes on MacOS using npm run.
• Updated relevant documentation and README (if needed).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request resolves a critical crash that occurred in subagents when using Model Context Protocol (MCP) tools. The root cause was a name mismatch, where the ToolRegistry provided short aliases for MCP tools while the LocalAgentExecutor expected fully qualified names. The fix is comprehensive: LocalAgentExecutor now automatically upgrades short names to their qualified form, and ToolRegistry has been updated to consistently return fully qualified names and deduplicate tool entries. These changes make the system more robust and align with the principle of least surprise. The implementation is clean, and the accompanying unit tests are thorough, correctly validating the new qualification and resolution logic. This is an excellent fix that improves both stability and developer experience.

[github-actions]

Size Change: +852 B (0%)

Total Size: 25.8 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	25.3 MB	+852 B (0%)
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B

_{compressed-size-action}