From 3ca505951e6a6bba59d85c3e481057a87ed2aab3 Mon Sep 17 00:00:00 2001
From: Abhi <abhipatel@google.com>
Date: Tue, 3 Mar 2026 19:43:57 -0500
Subject: [PATCH] docs: clarify MCP tool policies and name sanitization

- Explicitly document the requirement for qualified names (server__tool) or mcpName field for MCP tool allowlisting.
- Explain the security boundary preventing built-in tool rules from matching MCP tools.
- Document the 'Underscore Rule' for name sanitization (e.g., spaces to underscores).
---
 docs/reference/policy-engine.md | 24 ++++++++++++++++++++++++
 docs/tools/mcp-server.md        |  3 +++
 2 files changed, 27 insertions(+)

diff --git a/docs/reference/policy-engine.md b/docs/reference/policy-engine.md
index 17d958acd0..bfdcc8d634 100644
--- a/docs/reference/policy-engine.md
+++ b/docs/reference/policy-engine.md
@@ -74,12 +74,22 @@ primary conditions are the tool's name and its arguments.
 
 The `toolName` in the rule must match the name of the tool being called.
 
+- **Qualified MCP Names**: Tools from MCP servers are internally prefixed with
+  their server name (for example, `server__tool`). To match an MCP tool, you
+  must use the qualified name or the `mcpName` field. Unqualified names (for
+  example, `toolName = "my_tool"`) don't match MCP tools.
 - **Wildcards**: You can use wildcards to match multiple tools.
   - `*`: Matches **any tool** (built-in or MCP).
   - `server__*`: Matches any tool from a specific MCP server.
   - `*__toolName`: Matches a specific tool name across **all** MCP servers.
   - `*__*`: Matches **any tool from any MCP server**.
 
+> **Note:** **Built-in Protection**: Unqualified rules for built-in tools (like
+> `read_file` or `run_shell_command`) are strictly scoped. A rule for
+> `read_file` will only match the built-in tool and won't automatically allow
+> `my_server__read_file`. This prevents malicious servers from hijacking
+> permissions of built-in tools.
+
 #### Arguments pattern
 
 If `argsPattern` is specified, the tool's arguments are converted to a stable
@@ -165,6 +175,20 @@ A rule matches a tool call if all of its conditions are met:
     provided regular expression. If the arguments don't match the pattern, the
     rule does not apply.
 
+### Name sanitization (The "Underscore Rule")
+
+Gemini CLI sanitizes server and tool names to ensure compatibility with the
+Gemini API.
+
+- **Invalid characters**: Any character that is not a letter, number, underscore
+  (`_`), dot (`.`), colon (`:`), or hyphen (`-`) is replaced with an
+  **underscore**.
+- **Spaces**: Spaces are always converted to underscores. For example, a server
+  named `"Google Drive"` is registered as `"Google_Drive"`.
+- **Case sensitivity**: Matching is case-insensitive.
+
+Your TOML rules must use these sanitized names to match correctly at runtime.
+
 ## Configuration
 
 Policies are defined in `.toml` files. The CLI loads these files from Default,
diff --git a/docs/tools/mcp-server.md b/docs/tools/mcp-server.md
index 202325a83d..85fc89f1ca 100644
--- a/docs/tools/mcp-server.md
+++ b/docs/tools/mcp-server.md
@@ -559,6 +559,9 @@ Upon successful connection:
      with underscores
    - Names longer than 63 characters are truncated with middle replacement
      (`___`)
+   - See
+     [Name sanitization](/docs/reference/policy-engine.md#name-sanitization-the-underscore-rule)
+     in the policy engine reference for more details.
 
 ### 3. Conflict resolution