工具總覽
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 配置。