docs(mcp): standardize mcp tool fqn documentation

[abhipatel12]

Summary

Updates documentation across the repository to correctly reflect that MCP tools are unconditionally converted to Fully Qualified Names (FQNs) using the format mcp_serverName_toolName.

Details

Previously, the documentation stated that MCP tools received unprefixed names and were only prefixed (serverName__toolName) upon conflicts. The actual tool discovery mechanism now unconditionally applies the strict mcp_serverName_toolName FQN. This PR updates all examples and explanations in the docs to match the actual implementation. It also updates TOML policy examples to use the mcpName field instead of FQNs, which is the recommended approach.

Related Issues

N/A

How to Validate

Review the markdown changes in:

• docs/tools/mcp-server.md
• docs/reference/configuration.md
• docs/reference/policy-engine.md
• docs/extensions/reference.md
• docs/hooks/reference.md
• docs/cli/tutorials/mcp-setup.md

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
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[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 refines the documentation related to Model-Context Protocol (MCP) tools, ensuring that all references and examples accurately reflect the current implementation. The core change clarifies that MCP tools are consistently assigned a Fully Qualified Name (FQN) upon discovery, rather than only in cases of naming conflicts. This update aims to provide clearer and more accurate guidance for users configuring and interacting with MCP tools and policies.

Highlights

• Documentation Standardization: Updated documentation across the repository to accurately reflect that Model-Context Protocol (MCP) tools are unconditionally converted to Fully Qualified Names (FQNs).
• FQN Format Clarification: The standardized FQN format for MCP tools is mcp_serverName_toolName, correcting previous documentation that suggested conditional naming.
• TOML Policy Recommendations: TOML policy examples have been updated to recommend using the mcpName field instead of directly using FQNs for improved robustness.

Changelog

• docs/cli/tutorials/mcp-setup.md
  • Updated an example tool call to use the new fully qualified name format.
• docs/extensions/reference.md
  • Modified TOML policy examples to utilize separate mcpName and toolName fields for clarity.
• docs/hooks/reference.md
  • Corrected the documented naming pattern for MCP tools to reflect the mcp_server_tool format.
• docs/reference/configuration.md
  • Revised the description of MCP server configuration to state that all discovered tools are unconditionally assigned a fully qualified name.
• docs/reference/policy-engine.md
  • Updated MCP tool wildcard patterns to include the mcp_ prefix.
  • Added a recommendation to use the mcpName field for MCP policies instead of FQN wildcards.
  • Clarified the internal FQN format in the mcpName example comment.
  • Emphasized that the mcpName field is the recommended approach for defining MCP policies.
• docs/tools/mcp-server.md
  • Changed the truncation symbol for long names from ___ to ....
  • Completely revised the 'Conflict resolution' section to 'Tool naming and namespaces', detailing the unconditional FQN assignment, registry tracking, overwrite behavior, and linking to policy documentation.
  • Updated an example output to display fully qualified names for tools.

Activity

• No human activity has been recorded on this pull request yet.

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 updates documentation to standardize the naming convention for MCP tools to a fully qualified name (FQN). The changes are generally correct and improve clarity. However, the updated documentation contains two issues that could lead to significant user confusion and incorrect behavior, particularly with security policies. One is a critical omission regarding how server names with underscores are parsed, which can cause policies to fail silently. The other is a minor inaccuracy in the description of character sanitization.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[github-actions]

Size Change: -4 B (0%)

Total Size: 26 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	25.6 MB	-4 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}

[jkcinouye]

LGTM.