工具总览
Gemini CLI 工具系统总览：内置工具、MCP、extensions、policy engine 和权限确认的关系。
Gemini CLI 的工具系统让模型能读文件、写文件、跑命令、查网页、管理 todo、规划任务、连接外部服务。Google 官方文档把工具分散在 tutorials、tools reference、MCP 和 extensions 文档里。
工具系统可以按三层理解：内置工具负责本地文件、Shell、web 和 planning；MCP servers 负责连接 GitHub、数据库、Cloud 或自定义系统；Extensions 负责打包可复用能力。
先把内置工具和权限边界用稳，再接 MCP。MCP 会放大能力，也会放大凭据、网络和外部副作用风险。
flowchart LR
Prompt["用户任务"] --> Builtin["内置工具"]
Prompt --> MCP["MCP servers"]
Prompt --> Ext["Extensions"]
Builtin --> Local["文件 / Shell / Web / Planning"]
MCP --> External["GitHub / DB / Cloud / 自定义服务"]
Ext --> Package["可分发能力包"]
Local --> Policy["approval / sandbox / policy"]
External --> Policy
style Builtin fill:#dbeafe,stroke:#3b82f6
style MCP fill:#fef3c7,stroke:#f59e0b
style Policy fill:#fee2e2,stroke:#ef4444工具如何执行
工具通常由 Gemini CLI 自动调用。你也可以在 prompt 里用简写触发关键工具：
@path：读取文件或目录，触发文件读取能力。!command：执行 shell 命令，触发 shell 工具。
只读工具通常风险较低；会改文件或执行命令的 mutator 会触发确认，CLI 会展示 diff 或具体命令。Trusted folders、sandbox、policy engine 会共同影响工具是否能执行。
第一原则
| 问题 | 建议 |
|---|---|
| 能用内置工具解决吗 | 先用内置工具 |
| 是否需要外部系统 | 再接 MCP |
| 是否需要分发可复用能力 | 考虑 extension 或 skill |
| 是否涉及写操作 | 先看权限和 policy |
| 是否涉及生产环境 | 必须人工确认 |
读工具能力的顺序
先看内置工具能否完成任务，再判断是否需要 MCP。只有当能力需要长期分发、版本管理或团队共享时，再考虑 extension 或 skill。
常见工具族
- 文件系统：
glob、grep_search、list_directory、read_file、read_many_files、replace、write_file。 - Shell：
run_shell_command，可以执行命令、交互会话和后台进程。 - Web：
google_web_search和web_fetch。 - Planning：
enter_plan_mode、exit_plan_mode。 - Todos：
write_todos，用于长任务进度可视化。 - MCP resources：
list_mcp_resources、read_mcp_resource。 - Memory / Skills：
save_memory、activate_skill。
配置和验收
用 /tools 查看当前会话已注册工具，用 /tools desc 查看完整说明。接入 MCP 或 extension 后，第一步不是直接执行任务，而是先确认工具是否出现、描述是否正确、危险工具是否仍需要确认。
写 policy engine 规则时，官方 tools reference 给出了每个工具的 JSON argument keys。比如限制 write_file 写 .env，应该匹配 file_path，而不是只在自然语言里提醒模型。
接入验收清单
新增或调整工具后，至少检查四件事：
/tools能看到工具名。/tools desc的能力描述和实际权限一致。- 高风险动作仍会触发确认或 policy 拦截。
- 失败时能看到足够的错误信息，而不是静默跳过。
工具配置不应该只在“成功路径”测试。要专门试一次被拒绝的写文件、被拒绝的 shell、不可用的 MCP server，确认失败行为可理解、可恢复。
接下来去哪
文件系统工具
先看读文件、搜索、replace 和 write_file 的边界。
Shell 工具
继续看命令执行、后台进程、sandbox 和 policy 控制。
MCP setup
内置工具不够时，再进入 MCP server 配置。