From 192f4e7278ba09f22ddc9273a7fc942dbfdd6178 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Wed, 18 Feb 2026 09:51:22 -0800 Subject: [PATCH 01/12] Docs: Create tools reference page. --- docs/cli/enterprise.md | 2 +- docs/core/index.md | 4 +- docs/core/tools-api.md | 131 ---------------------------------------- docs/reference/tools.md | 126 ++++++++++++++++++++++++++++++++++++++ docs/sidebar.json | 2 +- 5 files changed, 130 insertions(+), 135 deletions(-) delete mode 100644 docs/core/tools-api.md create mode 100644 docs/reference/tools.md diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md index 31f7f89c837..29b125f60b7 100644 --- a/docs/cli/enterprise.md +++ b/docs/cli/enterprise.md @@ -289,7 +289,7 @@ unintended tool execution. ## Managing custom tools (MCP servers) If your organization uses custom tools via -[Model-Context Protocol (MCP) servers](../core/tools-api.md), it is crucial to +[Model-Context Protocol (MCP) servers](../tools/mcp-server.md), it is crucial to understand how server configurations are managed to apply security policies effectively. diff --git a/docs/core/index.md b/docs/core/index.md index 0cd49ad43e8..9bb3894ac44 100644 --- a/docs/core/index.md +++ b/docs/core/index.md @@ -9,8 +9,8 @@ requests sent from `packages/cli`. For a general overview of Gemini CLI, see the - **[Sub-agents (experimental)](./subagents.md):** Learn how to create and use specialized sub-agents for complex tasks. -- **[Core tools API](./tools-api.md):** Information on how tools are defined, - registered, and used by the core. +- **[Core tools reference](../reference/tools.md):** Information on how tools + are defined, registered, and used by the core. - **[Memory Import Processor](./memport.md):** Documentation for the modular GEMINI.md import feature using @file.md syntax. - **[Policy Engine](./policy-engine.md):** Use the Policy Engine for diff --git a/docs/core/tools-api.md b/docs/core/tools-api.md deleted file mode 100644 index 91fae3f720f..00000000000 --- a/docs/core/tools-api.md +++ /dev/null @@ -1,131 +0,0 @@ -# Gemini CLI core: Tools API - -The Gemini CLI core (`packages/core`) features a robust system for defining, -registering, and executing tools. These tools extend the capabilities of the -Gemini model, allowing it to interact with the local environment, fetch web -content, and perform various actions beyond simple text generation. - -## Core concepts - -- **Tool (`tools.ts`):** An interface and base class (`BaseTool`) that defines - the contract for all tools. Each tool must have: - - `name`: A unique internal name (used in API calls to Gemini). - - `displayName`: A user-friendly name. - - `description`: A clear explanation of what the tool does, which is provided - to the Gemini model. - - `parameterSchema`: A JSON schema defining the parameters that the tool - accepts. This is crucial for the Gemini model to understand how to call the - tool correctly. - - `validateToolParams()`: A method to validate incoming parameters. - - `getDescription()`: A method to provide a human-readable description of what - the tool will do with specific parameters before execution. - - `shouldConfirmExecute()`: A method to determine if user confirmation is - required before execution (e.g., for potentially destructive operations). - - `execute()`: The core method that performs the tool's action and returns a - `ToolResult`. - -- **`ToolResult` (`tools.ts`):** An interface defining the structure of a tool's - execution outcome: - - `llmContent`: The factual content to be included in the history sent back to - the LLM for context. This can be a simple string or a `PartListUnion` (an - array of `Part` objects and strings) for rich content. - - `returnDisplay`: A user-friendly string (often Markdown) or a special object - (like `FileDiff`) for display in the CLI. - -- **Returning rich content:** Tools are not limited to returning simple text. - The `llmContent` can be a `PartListUnion`, which is an array that can contain - a mix of `Part` objects (for images, audio, etc.) and `string`s. This allows a - single tool execution to return multiple pieces of rich content. - -- **Tool registry (`tool-registry.ts`):** A class (`ToolRegistry`) responsible - for: - - **Registering tools:** Holding a collection of all available built-in tools - (e.g., `ReadFileTool`, `ShellTool`). - - **Discovering tools:** It can also discover tools dynamically: - - **Command-based discovery:** If `tools.discoveryCommand` is configured in - settings, this command is executed. It's expected to output JSON - describing custom tools, which are then registered as `DiscoveredTool` - instances. - - **MCP-based discovery:** If `mcp.serverCommand` is configured, the - registry can connect to a Model Context Protocol (MCP) server to list and - register tools (`DiscoveredMCPTool`). - - **Providing schemas:** Exposing the `FunctionDeclaration` schemas of all - registered tools to the Gemini model, so it knows what tools are available - and how to use them. - - **Retrieving tools:** Allowing the core to get a specific tool by name for - execution. - -## Built-in tools - -The core comes with a suite of pre-defined tools, typically found in -`packages/core/src/tools/`. These include: - -- **File system tools:** - - `LSTool` (`ls.ts`): Lists directory contents. - - `ReadFileTool` (`read-file.ts`): Reads the content of a single file. - - `WriteFileTool` (`write-file.ts`): Writes content to a file. - - `GrepTool` (`grep.ts`): Searches for patterns in files. - - `GlobTool` (`glob.ts`): Finds files matching glob patterns. - - `EditTool` (`edit.ts`): Performs in-place modifications to files (often - requiring confirmation). - - `ReadManyFilesTool` (`read-many-files.ts`): Reads and concatenates content - from multiple files or glob patterns (used by the `@` command in CLI). -- **Execution tools:** - - `ShellTool` (`shell.ts`): Executes arbitrary shell commands (requires - careful sandboxing and user confirmation). -- **Web tools:** - - `WebFetchTool` (`web-fetch.ts`): Fetches content from a URL. - - `WebSearchTool` (`web-search.ts`): Performs a web search. -- **Memory tools:** - - `MemoryTool` (`memoryTool.ts`): Interacts with the AI's memory. - -Each of these tools extends `BaseTool` and implements the required methods for -its specific functionality. - -## Tool execution flow - -1. **Model request:** The Gemini model, based on the user's prompt and the - provided tool schemas, decides to use a tool and returns a `FunctionCall` - part in its response, specifying the tool name and arguments. -2. **Core receives request:** The core parses this `FunctionCall`. -3. **Tool retrieval:** It looks up the requested tool in the `ToolRegistry`. -4. **Parameter validation:** The tool's `validateToolParams()` method is - called. -5. **Confirmation (if needed):** - - The tool's `shouldConfirmExecute()` method is called. - - If it returns details for confirmation, the core communicates this back to - the CLI, which prompts the user. - - The user's decision (e.g., proceed, cancel) is sent back to the core. -6. **Execution:** If validated and confirmed (or if no confirmation is needed), - the core calls the tool's `execute()` method with the provided arguments and - an `AbortSignal` (for potential cancellation). -7. **Result processing:** The `ToolResult` from `execute()` is received by the - core. -8. **Response to model:** The `llmContent` from the `ToolResult` is packaged as - a `FunctionResponse` and sent back to the Gemini model so it can continue - generating a user-facing response. -9. **Display to user:** The `returnDisplay` from the `ToolResult` is sent to - the CLI to show the user what the tool did. - -## Extending with custom tools - -While direct programmatic registration of new tools by users isn't explicitly -detailed as a primary workflow in the provided files for typical end-users, the -architecture supports extension through: - -- **Command-based discovery:** Advanced users or project administrators can - define a `tools.discoveryCommand` in `settings.json`. This command, when run - by the Gemini CLI core, should output a JSON array of `FunctionDeclaration` - objects. The core will then make these available as `DiscoveredTool` - instances. The corresponding `tools.callCommand` would then be responsible for - actually executing these custom tools. -- **MCP server(s):** For more complex scenarios, one or more MCP servers can be - set up and configured via the `mcpServers` setting in `settings.json`. The - Gemini CLI core can then discover and use tools exposed by these servers. As - mentioned, if you have multiple MCP servers, the tool names will be prefixed - with the server name from your configuration (e.g., - `serverAlias__actualToolName`). - -This tool system provides a flexible and powerful way to augment the Gemini -model's capabilities, making the Gemini CLI a versatile assistant for a wide -range of tasks. diff --git a/docs/reference/tools.md b/docs/reference/tools.md new file mode 100644 index 00000000000..587f55bf56d --- /dev/null +++ b/docs/reference/tools.md @@ -0,0 +1,126 @@ +# Tools reference + +Gemini CLI uses tools to interact with your local environment, access +information, and perform actions on your behalf. These tools extend the model's +capabilities beyond text generation, letting it read files, execute commands, +and search the web. + +## Internal tools + +Internal tools are the bridge between the Gemini model and your local +environment. When you interact with Gemini CLI, the model can request to use one +or more of these tools to fulfill your request. Gemini CLI may also request +permission to use one or more of these tools. + +- **Operational tools** are used to perform actions that directly affect your + local environment, such as reading and writing files, executing commands, and + searching the web. These tools often require your confirmation before they are + executed. +- **Internal coordination tools** are used by the model to manage its own + internal state, such as tracking its progress on a task or accessing its own + documentation. These tools are often executed without your direct interaction. + +## The `/tools` command + +Explore the tools currently available to the Gemini model using the `/tools` +command. + +- **`/tools`**: Lists all registered tools with their display names. +- **`/tools desc`**: Lists all tools with their full descriptions as provided to + the Gemini model. + +This command is useful for verifying which tools are active, especially when +using custom tools via [MCP servers](../tools/mcp-server.md) or +[extensions](../extensions/index.md). + +## Operational tools + +This section provides a summary of the built-in operational tools available in +Gemini CLI. These tools are used to perform actions that directly affect your +local environment, such as reading and writing files, executing commands, and +searching the web. + +### File system tools + +These tools allow the model to explore and modify your local codebase. + +- **`list_directory`**: Lists the names of files and subdirectories within a + specified path. +- **`read_file`**: Reads the content of a specific file. Supports text, images, + audio, and PDF. +- **`write_file`**: Creates or overwrites a file with new content. Requires + manual confirmation. +- **`glob`**: Finds files matching specific glob patterns across the workspace. +- **`grep_search`**: Searches for a regular expression pattern within file + contents. +- **`replace`**: Performs precise text replacement within a file. Requires + manual confirmation. + +### Execution tools + +- **`run_shell_command`**: Executes arbitrary shell commands. Supports + interactive sessions and background processes. Requires manual confirmation. + +### Web tools + +- **`web_fetch`**: Retrieves and processes content from specific URLs. +- **`google_web_search`**: Performs a Google Search to find up-to-date + information. + +### User-facing tools + +- **`ask_user`**: Requests clarification or missing information via an + interactive dialog. +- **`enter_plan_mode`**: Switches the CLI to a safe, read-only "Plan Mode" for + researching complex changes. +- **`exit_plan_mode`**: Finalizes a plan, presents it for review, and requests + approval to start implementation. + +## Internal coordination tools + +This section provides a summary of the built-in internal coordination tools +available in Gemini CLI. These tools are used by the model to manage its own +internal state, such as tracking its progress on a task or accessing its own +documentation. + +- **`read_many_files`**: Reads and concatenates content from multiple files or + glob patterns. This tool is often triggered by the `@` symbol in the prompt, + but the model can also call it directly for broad context gathering. +- **`save_memory`**: Persists specific facts and project details to your + `GEMINI.md` file. While you can see the result, the model calls this tool + autonomously to retain context. +- **`write_todos`**: Maintains an internal list of subtasks for multi-step + requests. The model uses this to track its own progress, which is then + displayed to you. +- **`activate_skill`**: Loads specialized procedural expertise for specific + tasks from the `.gemini/skills` directory. +- **`get_internal_docs`**: Accesses Gemini CLI's own documentation to provide + more accurate answers about its capabilities. +- **`complete_task`**: Finalizes a subagent's mission and returns the result to + the parent agent. This tool is not available to the user. + +## Under the hood + +For developers, the tool system is designed to be extensible and robust. + +- **Tool registry**: The `ToolRegistry` class manages all available tools, + including built-in ones, those discovered via a `discoveryCommand`, and those + exposed by [MCP servers](../tools/mcp-server.md). +- **Tool execution flow**: + 1. The model returns a `FunctionCall` with a tool name and arguments. + 2. The core retrieves the tool from the registry and validates parameters. + 3. If required, the core requests user confirmation via the CLI. + 4. The tool's `execute()` method runs, returning a `ToolResult`. + 5. The result's `llmContent` is sent back to the model, and `returnDisplay` + is shown to the user. +- **Extensibility**: You can extend Gemini CLI with custom tools by configuring + a `tools.discoveryCommand` in your settings or by connecting to MCP servers. + +> **Note:** For a deep dive into the internal Tool API and how to implement your +> own tools in the codebase, see the `packages/core/src/tools/` directory. + +## Next steps + +- Learn how to [Set up an MCP server](../tools/mcp-server.md). +- Explore [Agent Skills](../cli/skills.md) for specialized expertise. +- See the [Command reference](../cli/commands.md) for more slash commands. diff --git a/docs/sidebar.json b/docs/sidebar.json index 617c31756e9..feea6c3e08a 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -152,7 +152,7 @@ { "label": "Keyboard shortcuts", "slug": "docs/cli/keyboard-shortcuts" }, { "label": "Memory import processor", "slug": "docs/core/memport" }, { "label": "Policy engine", "slug": "docs/core/policy-engine" }, - { "label": "Tools API", "slug": "docs/core/tools-api" } + { "label": "Tools reference", "slug": "docs/reference/tools" } ] }, { From 09e2ba26b7bf2237080cac46a12a3fe933df56b6 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Wed, 18 Feb 2026 13:21:22 -0800 Subject: [PATCH 02/12] Docs: Consolidate tools information. --- docs/reference/tools.md | 120 ++++++++++++++++++++-------------------- 1 file changed, 61 insertions(+), 59 deletions(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 587f55bf56d..3f0f82d1f3d 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -9,16 +9,22 @@ and search the web. Internal tools are the bridge between the Gemini model and your local environment. When you interact with Gemini CLI, the model can request to use one -or more of these tools to fulfill your request. Gemini CLI may also request -permission to use one or more of these tools. +or more of these tools to fulfill your request. -- **Operational tools** are used to perform actions that directly affect your - local environment, such as reading and writing files, executing commands, and - searching the web. These tools often require your confirmation before they are - executed. -- **Internal coordination tools** are used by the model to manage its own - internal state, such as tracking its progress on a task or accessing its own - documentation. These tools are often executed without your direct interaction. +Every tool has a technical **Kind** (such as `Read`, `Edit`, or `Execute`). This +classification helps the Gemini CLI [Policy Engine](../core/policy-engine.md) +determine security requirements. Tools categorized as **Mutators** (such as +`Edit` and `Execute`) typically require your manual confirmation before they +run, as they can modify your system or files. + +The tools are organized into three main categories: + +- **Environment tools** let the model interact with your file system, shell, and + the web. +- **Agent workflow tools** let the executive model manage the conversation flow, + gather your feedback, and plan complex tasks. +- **Internal coordination tools** let the model manage its own internal state, + access documentation, or return results from sub-agents. ## The `/tools` command @@ -33,71 +39,67 @@ This command is useful for verifying which tools are active, especially when using custom tools via [MCP servers](../tools/mcp-server.md) or [extensions](../extensions/index.md). -## Operational tools +## Environment tools -This section provides a summary of the built-in operational tools available in -Gemini CLI. These tools are used to perform actions that directly affect your -local environment, such as reading and writing files, executing commands, and -searching the web. +Environment tools let the model perform actions that directly affect your local +system, such as reading and writing files, executing commands, and searching the +web. ### File system tools -These tools allow the model to explore and modify your local codebase. +These tools let the model explore and modify your local codebase. -- **`list_directory`**: Lists the names of files and subdirectories within a - specified path. -- **`read_file`**: Reads the content of a specific file. Supports text, images, - audio, and PDF. -- **`write_file`**: Creates or overwrites a file with new content. Requires - manual confirmation. -- **`glob`**: Finds files matching specific glob patterns across the workspace. -- **`grep_search`**: Searches for a regular expression pattern within file - contents. -- **`replace`**: Performs precise text replacement within a file. Requires - manual confirmation. +| Tool | Kind | Parameters | Description | +| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `list_directory` | `Read` | `dir_path`, `ignore`, `file_filtering_options` | Lists the names of files and subdirectories within a specified path. | +| `read_file` | `Read` | `file_path`, `offset`, `limit` | Reads the content of a specific file. Supports text, images, audio, and PDF. | +| `write_file` | `Edit` | `file_path`, `content` | Creates or overwrites a file with new content. Requires manual confirmation. | +| `glob` | `Search` | `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | Finds files matching specific glob patterns across the workspace. | +| `grep_search` | `Search` | `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`. | +| `replace` | `Edit` | `file_path`, `old_string`, `new_string`, `expected_replacements`, `instruction` | Performs precise text replacement within a file. Requires manual confirmation. | ### Execution tools -- **`run_shell_command`**: Executes arbitrary shell commands. Supports - interactive sessions and background processes. Requires manual confirmation. +The execution tool lets the model run shell commands on your local machine. + +| Tool | Kind | Parameters | Description | +| ------------------- | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `run_shell_command` | `Execute` | `command`, `description`, `dir_path`, `is_background` | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation. | ### Web tools -- **`web_fetch`**: Retrieves and processes content from specific URLs. -- **`google_web_search`**: Performs a Google Search to find up-to-date - information. +Web tools let the model fetch content from URLs and perform web searches. -### User-facing tools +| Tool | Kind | Parameters | Description | +| ------------------- | -------- | ---------- | -------------------------------------------------------- | +| `web_fetch` | `Fetch` | `prompt` | Retrieves and processes content from specific URLs. | +| `google_web_search` | `Search` | `query` | Performs a Google Search to find up-to-date information. | -- **`ask_user`**: Requests clarification or missing information via an - interactive dialog. -- **`enter_plan_mode`**: Switches the CLI to a safe, read-only "Plan Mode" for - researching complex changes. -- **`exit_plan_mode`**: Finalizes a plan, presents it for review, and requests - approval to start implementation. +## Agent workflow tools + +Agent workflow tools let the model interact with you, plan its approach, and +track its progress through multi-step tasks. + +| Tool | Kind | Parameters | Description | +| ----------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | +| `ask_user` | `Communicate` | `questions` | Requests clarification or missing information via an interactive dialog. | +| `enter_plan_mode` | `Plan` | `reason` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes. | +| `exit_plan_mode` | `Plan` | `plan` | Finalizes a plan, presents it for review, and requests approval to start implementation. | +| `write_todos` | `Other` | `todos` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you. | ## Internal coordination tools -This section provides a summary of the built-in internal coordination tools -available in Gemini CLI. These tools are used by the model to manage its own -internal state, such as tracking its progress on a task or accessing its own -documentation. - -- **`read_many_files`**: Reads and concatenates content from multiple files or - glob patterns. This tool is often triggered by the `@` symbol in the prompt, - but the model can also call it directly for broad context gathering. -- **`save_memory`**: Persists specific facts and project details to your - `GEMINI.md` file. While you can see the result, the model calls this tool - autonomously to retain context. -- **`write_todos`**: Maintains an internal list of subtasks for multi-step - requests. The model uses this to track its own progress, which is then - displayed to you. -- **`activate_skill`**: Loads specialized procedural expertise for specific - tasks from the `.gemini/skills` directory. -- **`get_internal_docs`**: Accesses Gemini CLI's own documentation to provide - more accurate answers about its capabilities. -- **`complete_task`**: Finalizes a subagent's mission and returns the result to - the parent agent. This tool is not available to the user. +Internal coordination tools let the model manage its own internal state, access +its documentation, and handle specialized sub-tasks. These tools usually run +without your direct interaction. + +| Tool | Kind | Parameters | Description | +| ------------------- | ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `read_many_files` | `Read` | `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt. | +| `save_memory` | `Think` | `fact` | Persists specific facts and project details to your `GEMINI.md` file to retain context across sessions. | +| `activate_skill` | `Other` | `name` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory. | +| `get_internal_docs` | `Think` | `path` | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities. | +| `complete_task` | `Other` | `result` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user. | ## Under the hood @@ -123,4 +125,4 @@ For developers, the tool system is designed to be extensible and robust. - Learn how to [Set up an MCP server](../tools/mcp-server.md). - Explore [Agent Skills](../cli/skills.md) for specialized expertise. -- See the [Command reference](../cli/commands.md) for more slash commands. +- See the [Command reference](../cli/commands.md) for slash commands. From 1e0ba4ca8347f4dae8a81f63f152793ffba457f6 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Wed, 18 Feb 2026 13:28:43 -0800 Subject: [PATCH 03/12] Docs: Update tools.md --- docs/reference/tools.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 3f0f82d1f3d..65edbe11dfe 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -36,8 +36,7 @@ command. the Gemini model. This command is useful for verifying which tools are active, especially when -using custom tools via [MCP servers](../tools/mcp-server.md) or -[extensions](../extensions/index.md). +using custom tools. ## Environment tools From 6fa3d73a7ab0ad4ca7556fc61df5d9a862173f59 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Wed, 18 Feb 2026 13:51:07 -0800 Subject: [PATCH 04/12] Docs: Update and consolidate tools reference --- README.md | 4 +- docs/cli/enterprise.md | 2 +- docs/reference/tools.md | 117 +++++++++++++++++++++------------------- docs/tools/index.md | 102 ----------------------------------- 4 files changed, 66 insertions(+), 159 deletions(-) delete mode 100644 docs/tools/index.md diff --git a/README.md b/README.md index 6e9b1da1467..d88b76d1b65 100644 --- a/README.md +++ b/README.md @@ -301,7 +301,7 @@ gemini ### Tools & Extensions -- [**Built-in Tools Overview**](./docs/tools/index.md) +- [**Built-in Tools Overview**](./docs/reference/tools.md) - [File System Operations](./docs/tools/file-system.md) - [Shell Commands](./docs/tools/shell.md) - [Web Fetch & Search](./docs/tools/web-fetch.md) @@ -323,7 +323,7 @@ gemini - [**Enterprise Guide**](./docs/cli/enterprise.md) - Deploy and manage in a corporate environment. - [**Telemetry & Monitoring**](./docs/cli/telemetry.md) - Usage tracking. -- [**Tools API Development**](./docs/core/tools-api.md) - Create custom tools. +- [**Tools reference**](./docs/reference/tools.md) - Built-in tools overview. - [**Local development**](./docs/local-development.md) - Local development tooling. diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md index 29b125f60b7..f2af5258209 100644 --- a/docs/cli/enterprise.md +++ b/docs/cli/enterprise.md @@ -225,7 +225,7 @@ gemini You can significantly enhance security by controlling which tools the Gemini model can use. This is achieved through the `tools.core` setting and the [Policy Engine](../core/policy-engine.md). For a list of available tools, see -the [Tools documentation](../tools/index.md). +the [Tools reference](../reference/tools.md). ### Allowlisting with `coreTools` diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 65edbe11dfe..aa6f3f98e92 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -5,18 +5,6 @@ information, and perform actions on your behalf. These tools extend the model's capabilities beyond text generation, letting it read files, execute commands, and search the web. -## Internal tools - -Internal tools are the bridge between the Gemini model and your local -environment. When you interact with Gemini CLI, the model can request to use one -or more of these tools to fulfill your request. - -Every tool has a technical **Kind** (such as `Read`, `Edit`, or `Execute`). This -classification helps the Gemini CLI [Policy Engine](../core/policy-engine.md) -determine security requirements. Tools categorized as **Mutators** (such as -`Edit` and `Execute`) typically require your manual confirmation before they -run, as they can modify your system or files. - The tools are organized into three main categories: - **Environment tools** let the model interact with your file system, shell, and @@ -26,6 +14,36 @@ The tools are organized into three main categories: - **Internal coordination tools** let the model manage its own internal state, access documentation, or return results from sub-agents. +## Security and confirmation + +Every tool has a technical **Kind** (such as `Read`, `Edit`, or `Execute`). This +classification helps the Gemini CLI [Policy Engine](../core/policy-engine.md) +determine security requirements. + +- **User confirmation:** You must manually approve tools that modify files or + execute shell commands (Mutators). The CLI shows you a diff or the exact + command before you confirm. +- **Sandboxing:** You can run tool executions in secure, containerized + environments to isolate changes from your host system. For more details, see + the [Sandboxing](../cli/sandbox.md) guide. +- **Trusted folders:** You can configure which directories allow the model to + use system tools. For more details, see the + [Trusted folders](../cli/trusted-folders.md) guide. + +Always review confirmation prompts carefully before allowing a tool to execute. + +## User-triggered tools + +Most of Gemini CLI's tools are triggered by Gemini CLI. There are two tools you +directkly trigger using special syntax: + +- **[File access](../tools/file-system.md#read_many_files) (`@`):** Use the `@` + symbol followed by a file or directory path to include its content in your + prompt. This triggers the `read_many_files` tool. +- **[Shell commands](../tools/shell.md) (`!`):** Use the `!` symbol followed by + a system command to execute it directly. This triggers the `run_shell_command` + tool. + ## The `/tools` command Explore the tools currently available to the Gemini model using the `/tools` @@ -48,43 +66,43 @@ web. These tools let the model explore and modify your local codebase. -| Tool | Kind | Parameters | Description | -| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| `list_directory` | `Read` | `dir_path`, `ignore`, `file_filtering_options` | Lists the names of files and subdirectories within a specified path. | -| `read_file` | `Read` | `file_path`, `offset`, `limit` | Reads the content of a specific file. Supports text, images, audio, and PDF. | -| `write_file` | `Edit` | `file_path`, `content` | Creates or overwrites a file with new content. Requires manual confirmation. | -| `glob` | `Search` | `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | Finds files matching specific glob patterns across the workspace. | -| `grep_search` | `Search` | `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`. | -| `replace` | `Edit` | `file_path`, `old_string`, `new_string`, `expected_replacements`, `instruction` | Performs precise text replacement within a file. Requires manual confirmation. | +| Tool | Kind | Parameters | Description | +| ------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| [`list_directory`](../tools/file-system.md) | `Read` | `dir_path`, `ignore`, `file_filtering_options` | Lists the names of files and subdirectories within a specified path. | +| [`read_file`](../tools/file-system.md) | `Read` | `file_path`, `offset`, `limit` | Reads the content of a specific file. Supports text, images, audio, and PDF. | +| [`write_file`](../tools/file-system.md) | `Edit` | `file_path`, `content` | Creates or overwrites a file with new content. Requires manual confirmation. | +| [`glob`](../tools/file-system.md) | `Search` | `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | Finds files matching specific glob patterns across the workspace. | +| [`grep_search`](../tools/file-system.md) | `Search` | `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`. | +| [`replace`](../tools/file-system.md) | `Edit` | `file_path`, `old_string`, `new_string`, `expected_replacements`, `instruction` | Performs precise text replacement within a file. Requires manual confirmation. | ### Execution tools The execution tool lets the model run shell commands on your local machine. -| Tool | Kind | Parameters | Description | -| ------------------- | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `run_shell_command` | `Execute` | `command`, `description`, `dir_path`, `is_background` | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation. | +| Tool | Kind | Parameters | Description | +| ---------------------------------------- | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| [`run_shell_command`](../tools/shell.md) | `Execute` | `command`, `description`, `dir_path`, `is_background` | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation. | ### Web tools Web tools let the model fetch content from URLs and perform web searches. -| Tool | Kind | Parameters | Description | -| ------------------- | -------- | ---------- | -------------------------------------------------------- | -| `web_fetch` | `Fetch` | `prompt` | Retrieves and processes content from specific URLs. | -| `google_web_search` | `Search` | `query` | Performs a Google Search to find up-to-date information. | +| Tool | Kind | Parameters | Description | +| --------------------------------------------- | -------- | ---------- | -------------------------------------------------------- | +| [`web_fetch`](../tools/web-fetch.md) | `Fetch` | `prompt` | Retrieves and processes content from specific URLs. | +| [`google_web_search`](../tools/web-search.md) | `Search` | `query` | Performs a Google Search to find up-to-date information. | ## Agent workflow tools Agent workflow tools let the model interact with you, plan its approach, and track its progress through multi-step tasks. -| Tool | Kind | Parameters | Description | -| ----------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | -| `ask_user` | `Communicate` | `questions` | Requests clarification or missing information via an interactive dialog. | -| `enter_plan_mode` | `Plan` | `reason` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes. | -| `exit_plan_mode` | `Plan` | `plan` | Finalizes a plan, presents it for review, and requests approval to start implementation. | -| `write_todos` | `Other` | `todos` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you. | +| Tool | Kind | Parameters | Description | +| ----------------------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | +| [`ask_user`](../tools/ask-user.md) | `Communicate` | `questions` | Requests clarification or missing information via an interactive dialog. | +| [`enter_plan_mode`](../tools/planning.md) | `Plan` | `reason` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes. | +| [`exit_plan_mode`](../tools/planning.md) | `Plan` | `plan` | Finalizes a plan, presents it for review, and requests approval to start implementation. | +| [`write_todos`](../tools/todos.md) | `Other` | `todos` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you. | ## Internal coordination tools @@ -92,30 +110,21 @@ Internal coordination tools let the model manage its own internal state, access its documentation, and handle specialized sub-tasks. These tools usually run without your direct interaction. -| Tool | Kind | Parameters | Description | -| ------------------- | ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `read_many_files` | `Read` | `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt. | -| `save_memory` | `Think` | `fact` | Persists specific facts and project details to your `GEMINI.md` file to retain context across sessions. | -| `activate_skill` | `Other` | `name` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory. | -| `get_internal_docs` | `Think` | `path` | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities. | -| `complete_task` | `Other` | `result` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user. | +| Tool | Kind | Parameters | Description | +| ------------------------------------------------ | ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| [`read_many_files`](../tools/file-system.md) | `Read` | `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt. | +| [`save_memory`](../tools/memory.md) | `Think` | `fact` | Persists specific facts and project details to your `GEMINI.md` file to retain context across sessions. | +| [`activate_skill`](../tools/activate-skill.md) | `Other` | `name` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory. | +| [`get_internal_docs`](../tools/internal-docs.md) | `Think` | `path` | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities. | +| `complete_task` | `Other` | `result` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user. | ## Under the hood -For developers, the tool system is designed to be extensible and robust. - -- **Tool registry**: The `ToolRegistry` class manages all available tools, - including built-in ones, those discovered via a `discoveryCommand`, and those - exposed by [MCP servers](../tools/mcp-server.md). -- **Tool execution flow**: - 1. The model returns a `FunctionCall` with a tool name and arguments. - 2. The core retrieves the tool from the registry and validates parameters. - 3. If required, the core requests user confirmation via the CLI. - 4. The tool's `execute()` method runs, returning a `ToolResult`. - 5. The result's `llmContent` is sent back to the model, and `returnDisplay` - is shown to the user. -- **Extensibility**: You can extend Gemini CLI with custom tools by configuring - a `tools.discoveryCommand` in your settings or by connecting to MCP servers. +For developers, the tool system is designed to be extensible and robust. The +`ToolRegistry` class manages all available tools. + +You can extend Gemini CLI with custom tools by configuring a +`tools.discoveryCommand` in your settings or by connecting to MCP servers. > **Note:** For a deep dive into the internal Tool API and how to implement your > own tools in the codebase, see the `packages/core/src/tools/` directory. diff --git a/docs/tools/index.md b/docs/tools/index.md deleted file mode 100644 index 42304ef0084..00000000000 --- a/docs/tools/index.md +++ /dev/null @@ -1,102 +0,0 @@ -# Gemini CLI tools - -Gemini CLI uses tools to interact with your local environment, access -information, and perform actions on your behalf. These tools extend the model's -capabilities beyond text generation, letting it read files, execute commands, -and search the web. - -## User-triggered tools - -You can directly trigger these tools using special syntax in your prompts. - -- **[File access](./file-system.md#read_many_files) (`@`):** Use the `@` symbol - followed by a file or directory path to include its content in your prompt. - This triggers the `read_many_files` tool. -- **[Shell commands](./shell.md) (`!`):** Use the `!` symbol followed by a - system command to execute it directly. This triggers the `run_shell_command` - tool. - -## Model-triggered tools - -The Gemini model automatically requests these tools when it needs to perform -specific actions or gather information to fulfill your requests. You do not call -these tools manually. - -### File management - -These tools let the model explore and modify your local codebase. - -- **[Directory listing](./file-system.md#list_directory) (`list_directory`):** - Lists files and subdirectories. -- **[File reading](./file-system.md#read_file) (`read_file`):** Reads the - content of a specific file. -- **[File writing](./file-system.md#write_file) (`write_file`):** Creates or - overwrites a file with new content. -- **[File search](./file-system.md#glob) (`glob`):** Finds files matching a glob - pattern. -- **[Text search](./file-system.md#search_file_content) - (`search_file_content`):** Searches for text within files using grep or - ripgrep. -- **[Text replacement](./file-system.md#replace) (`replace`):** Performs precise - edits within a file. - -### Agent coordination - -These tools help the model manage its plan and interact with you. - -- **Ask user (`ask_user`):** Requests clarification or missing information from - you via an interactive dialog. -- **[Memory](./memory.md) (`save_memory`):** Saves important facts to your - long-term memory (`GEMINI.md`). -- **[Todos](./todos.md) (`write_todos`):** Manages a list of subtasks for - complex plans. -- **[Agent Skills](../cli/skills.md) (`activate_skill`):** Loads specialized - procedural expertise when needed. -- **Internal docs (`get_internal_docs`):** Accesses Gemini CLI's own - documentation to help answer your questions. - -### Information gathering - -These tools provide the model with access to external data. - -- **[Web fetch](./web-fetch.md) (`web_fetch`):** Retrieves and processes content - from specific URLs. -- **[Web search](./web-search.md) (`google_web_search`):** Performs a Google - Search to find up-to-date information. - -## How to use tools - -You use tools indirectly by providing natural language prompts to Gemini CLI. - -1. **Prompt:** You enter a request or use syntax like `@` or `!`. -2. **Request:** The model analyzes your request and identifies if a tool is - required. -3. **Validation:** If a tool is needed, the CLI validates the parameters and - checks your security settings. -4. **Confirmation:** For sensitive operations (like writing files), the CLI - prompts you for approval. -5. **Execution:** The tool runs, and its output is sent back to the model. -6. **Response:** The model uses the results to generate a final, grounded - answer. - -## Security and confirmation - -Safety is a core part of the tool system. To protect your system, Gemini CLI -implements several safeguards. - -- **User confirmation:** You must manually approve tools that modify files or - execute shell commands. The CLI shows you a diff or the exact command before - you confirm. -- **Sandboxing:** You can run tool executions in secure, containerized - environments to isolate changes from your host system. For more details, see - the [Sandboxing](../cli/sandbox.md) guide. -- **Trusted folders:** You can configure which directories allow the model to - use system tools. - -Always review confirmation prompts carefully before allowing a tool to execute. - -## Next steps - -- Learn how to [Provide context](../cli/gemini-md.md) to guide tool use. -- Explore the [Command reference](../cli/commands.md) for tool-related slash - commands. From d292ce459e9dcc5c5a184cb6ad1d9662f3fd1f91 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Fri, 20 Feb 2026 12:26:31 -0800 Subject: [PATCH 05/12] Docs: Revise tools API guidance into reference materials. --- docs/reference/tools.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index aa6f3f98e92..0190585be69 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -21,7 +21,7 @@ classification helps the Gemini CLI [Policy Engine](../core/policy-engine.md) determine security requirements. - **User confirmation:** You must manually approve tools that modify files or - execute shell commands (Mutators). The CLI shows you a diff or the exact + execute shell commands (mutators). The CLI shows you a diff or the exact command before you confirm. - **Sandboxing:** You can run tool executions in secure, containerized environments to isolate changes from your host system. For more details, see @@ -35,7 +35,7 @@ Always review confirmation prompts carefully before allowing a tool to execute. ## User-triggered tools Most of Gemini CLI's tools are triggered by Gemini CLI. There are two tools you -directkly trigger using special syntax: +can directly trigger using special syntax: - **[File access](../tools/file-system.md#read_many_files) (`@`):** Use the `@` symbol followed by a file or directory path to include its content in your @@ -46,12 +46,12 @@ directkly trigger using special syntax: ## The `/tools` command -Explore the tools currently available to the Gemini model using the `/tools` +You can explore the tools currently available to Gemini CLI using the `/tools` command. - **`/tools`**: Lists all registered tools with their display names. - **`/tools desc`**: Lists all tools with their full descriptions as provided to - the Gemini model. + Gemini CLI. This command is useful for verifying which tools are active, especially when using custom tools. @@ -64,7 +64,7 @@ web. ### File system tools -These tools let the model explore and modify your local codebase. +Explore and modify your local codebase. | Tool | Kind | Parameters | Description | | ------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | @@ -77,7 +77,7 @@ These tools let the model explore and modify your local codebase. ### Execution tools -The execution tool lets the model run shell commands on your local machine. +Let the model run shell commands on your local machine. | Tool | Kind | Parameters | Description | | ---------------------------------------- | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | @@ -85,7 +85,7 @@ The execution tool lets the model run shell commands on your local machine. ### Web tools -Web tools let the model fetch content from URLs and perform web searches. +Let the model fetch content from URLs and perform web searches. | Tool | Kind | Parameters | Description | | --------------------------------------------- | -------- | ---------- | -------------------------------------------------------- | @@ -94,8 +94,8 @@ Web tools let the model fetch content from URLs and perform web searches. ## Agent workflow tools -Agent workflow tools let the model interact with you, plan its approach, and -track its progress through multi-step tasks. +Let the model interact with you, plan its approach, and track its progress +through multi-step tasks. | Tool | Kind | Parameters | Description | | ----------------------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | @@ -106,9 +106,9 @@ track its progress through multi-step tasks. ## Internal coordination tools -Internal coordination tools let the model manage its own internal state, access -its documentation, and handle specialized sub-tasks. These tools usually run -without your direct interaction. +Let the model manage its own internal state, access its documentation, and +handle specialized sub-tasks. These tools usually run without your direct +interaction. | Tool | Kind | Parameters | Description | | ------------------------------------------------ | ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | @@ -123,7 +123,7 @@ without your direct interaction. For developers, the tool system is designed to be extensible and robust. The `ToolRegistry` class manages all available tools. -You can extend Gemini CLI with custom tools by configuring a +You can extend Gemini CLI with custom tools by configuring `tools.discoveryCommand` in your settings or by connecting to MCP servers. > **Note:** For a deep dive into the internal Tool API and how to implement your From 57af67a9edfb6c38a71888632c69f557c69b7605 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Mon, 23 Feb 2026 09:04:27 -0800 Subject: [PATCH 06/12] Docs: Update tools reference. --- docs/reference/tools.md | 140 ++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 85 deletions(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 0190585be69..6c2b212c745 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -5,20 +5,16 @@ information, and perform actions on your behalf. These tools extend the model's capabilities beyond text generation, letting it read files, execute commands, and search the web. -The tools are organized into three main categories: +## How to use Gemini CLI's tools -- **Environment tools** let the model interact with your file system, shell, and - the web. -- **Agent workflow tools** let the executive model manage the conversation flow, - gather your feedback, and plan complex tasks. -- **Internal coordination tools** let the model manage its own internal state, - access documentation, or return results from sub-agents. +Tools are generally invoked automatically by Gemini CLI when it needs to perform +an action. However, you can also trigger specific tools manually using shorthand +syntax. -## Security and confirmation +### Automatic execution and security -Every tool has a technical **Kind** (such as `Read`, `Edit`, or `Execute`). This -classification helps the Gemini CLI [Policy Engine](../core/policy-engine.md) -determine security requirements. +When the model wants to use a tool, Gemini CLI evaluates the request against its +security policies. - **User confirmation:** You must manually approve tools that modify files or execute shell commands (mutators). The CLI shows you a diff or the exact @@ -30,12 +26,11 @@ determine security requirements. use system tools. For more details, see the [Trusted folders](../cli/trusted-folders.md) guide. -Always review confirmation prompts carefully before allowing a tool to execute. +Review confirmation prompts carefully before allowing a tool to execute. -## User-triggered tools +### How to use manually-triggered tools -Most of Gemini CLI's tools are triggered by Gemini CLI. There are two tools you -can directly trigger using special syntax: +You can directly trigger key tools using special syntax in your prompt: - **[File access](../tools/file-system.md#read_many_files) (`@`):** Use the `@` symbol followed by a file or directory path to include its content in your @@ -44,79 +39,53 @@ can directly trigger using special syntax: a system command to execute it directly. This triggers the `run_shell_command` tool. -## The `/tools` command +## How to manage tools -You can explore the tools currently available to Gemini CLI using the `/tools` -command. +Using built-in commands, you can inspect available tools and configure how they +behave. -- **`/tools`**: Lists all registered tools with their display names. -- **`/tools desc`**: Lists all tools with their full descriptions as provided to - Gemini CLI. - -This command is useful for verifying which tools are active, especially when -using custom tools. - -## Environment tools - -Environment tools let the model perform actions that directly affect your local -system, such as reading and writing files, executing commands, and searching the -web. - -### File system tools - -Explore and modify your local codebase. - -| Tool | Kind | Parameters | Description | -| ------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| [`list_directory`](../tools/file-system.md) | `Read` | `dir_path`, `ignore`, `file_filtering_options` | Lists the names of files and subdirectories within a specified path. | -| [`read_file`](../tools/file-system.md) | `Read` | `file_path`, `offset`, `limit` | Reads the content of a specific file. Supports text, images, audio, and PDF. | -| [`write_file`](../tools/file-system.md) | `Edit` | `file_path`, `content` | Creates or overwrites a file with new content. Requires manual confirmation. | -| [`glob`](../tools/file-system.md) | `Search` | `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | Finds files matching specific glob patterns across the workspace. | -| [`grep_search`](../tools/file-system.md) | `Search` | `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`. | -| [`replace`](../tools/file-system.md) | `Edit` | `file_path`, `old_string`, `new_string`, `expected_replacements`, `instruction` | Performs precise text replacement within a file. Requires manual confirmation. | - -### Execution tools - -Let the model run shell commands on your local machine. +### Tool discovery -| Tool | Kind | Parameters | Description | -| ---------------------------------------- | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| [`run_shell_command`](../tools/shell.md) | `Execute` | `command`, `description`, `dir_path`, `is_background` | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation. | +Use the `/tools` command to see what tools are currently active in your session. -### Web tools - -Let the model fetch content from URLs and perform web searches. - -| Tool | Kind | Parameters | Description | -| --------------------------------------------- | -------- | ---------- | -------------------------------------------------------- | -| [`web_fetch`](../tools/web-fetch.md) | `Fetch` | `prompt` | Retrieves and processes content from specific URLs. | -| [`google_web_search`](../tools/web-search.md) | `Search` | `query` | Performs a Google Search to find up-to-date information. | - -## Agent workflow tools - -Let the model interact with you, plan its approach, and track its progress -through multi-step tasks. - -| Tool | Kind | Parameters | Description | -| ----------------------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | -| [`ask_user`](../tools/ask-user.md) | `Communicate` | `questions` | Requests clarification or missing information via an interactive dialog. | -| [`enter_plan_mode`](../tools/planning.md) | `Plan` | `reason` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes. | -| [`exit_plan_mode`](../tools/planning.md) | `Plan` | `plan` | Finalizes a plan, presents it for review, and requests approval to start implementation. | -| [`write_todos`](../tools/todos.md) | `Other` | `todos` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you. | - -## Internal coordination tools - -Let the model manage its own internal state, access its documentation, and -handle specialized sub-tasks. These tools usually run without your direct -interaction. - -| Tool | Kind | Parameters | Description | -| ------------------------------------------------ | ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| [`read_many_files`](../tools/file-system.md) | `Read` | `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt. | -| [`save_memory`](../tools/memory.md) | `Think` | `fact` | Persists specific facts and project details to your `GEMINI.md` file to retain context across sessions. | -| [`activate_skill`](../tools/activate-skill.md) | `Other` | `name` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory. | -| [`get_internal_docs`](../tools/internal-docs.md) | `Think` | `path` | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities. | -| `complete_task` | `Other` | `result` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user. | +- **`/tools`**: Lists all registered tools with their display names. +- **`/tools desc`**: Lists all tools with their full descriptions. + +This is especially useful for verifying that +[MCP servers](../tools/mcp-server.md) or custom tools are loaded correctly. + +### Tool configuration + +You can enable, disable, or configure specific tools in your settings. For +example, you can set a specific pager for shell commands or configure the +browser used for web searches. See the [Settings](../cli/settings.md) guide for +details. + +## Available tools + +The following table lists all available tools, categorized by their primary +function. + +| Category | Tool | Kind | Description | +| :---------- | :----------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Execution | [`run_shell_command`](../tools/shell.md) | `Execute` | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation.

**Parameters:** `command`, `description`, `dir_path`, `is_background` | +| File System | [`glob`](../tools/file-system.md) | `Search` | Finds files matching specific glob patterns across the workspace.

**Parameters:** `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | +| File System | [`grep_search`](../tools/file-system.md) | `Search` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`.

**Parameters:** `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | +| File System | [`list_directory`](../tools/file-system.md) | `Read` | Lists the names of files and subdirectories within a specified path.

**Parameters:** `dir_path`, `ignore`, `file_filtering_options` | +| File System | [`read_file`](../tools/file-system.md) | `Read` | Reads the content of a specific file. Supports text, images, audio, and PDF.

**Parameters:** `file_path`, `offset`, `limit` | +| File System | [`read_many_files`](../tools/file-system.md) | `Read` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt.

**Parameters:** `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | +| File System | [`replace`](../tools/file-system.md) | `Edit` | Performs precise text replacement within a file. Requires manual confirmation.

**Parameters:** `file_path`, `old_string`, `new_string`, `expected_replacements`, `instruction` | +| File System | [`write_file`](../tools/file-system.md) | `Edit` | Creates or overwrites a file with new content. Requires manual confirmation.

**Parameters:** `file_path`, `content` | +| Interaction | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog.

**Parameters:** `questions` | +| Interaction | [`write_todos`](../tools/todos.md) | `Other` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you.

**Parameters:** `todos` | +| Memory | [`activate_skill`](../tools/activate-skill.md) | `Other` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory.

**Parameters:** `name` | +| Memory | [`get_internal_docs`](../tools/internal-docs.md) | `Think` | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities.

**Parameters:** `path` | +| Memory | [`save_memory`](../tools/memory.md) | `Think` | Persists specific facts and project details to your `GEMINI.md` file to retain context.

**Parameters:** `fact` | +| Planning | [`enter_plan_mode`](../tools/planning.md) | `Plan` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes.

**Parameters:** `reason` | +| Planning | [`exit_plan_mode`](../tools/planning.md) | `Plan` | Finalizes a plan, presents it for review, and requests approval to start implementation.

**Parameters:** `plan` | +| System | `complete_task` | `Other` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user.

**Parameters:** `result` | +| Web | [`google_web_search`](../tools/web-search.md) | `Search` | Performs a Google Search to find up-to-date information.

**Parameters:** `query` | +| Web | [`web_fetch`](../tools/web-fetch.md) | `Fetch` | Retrieves and processes content from specific URLs.

**Parameters:** `prompt` | ## Under the hood @@ -127,7 +96,8 @@ You can extend Gemini CLI with custom tools by configuring `tools.discoveryCommand` in your settings or by connecting to MCP servers. > **Note:** For a deep dive into the internal Tool API and how to implement your -> own tools in the codebase, see the `packages/core/src/tools/` directory. +> own tools in the codebase, see the `packages/core/src/tools/` directory in +> GitHub. ## Next steps From 643964327b781f83189914234694e4f8704c3846 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Tue, 24 Feb 2026 12:01:03 -0800 Subject: [PATCH 07/12] Docs: Fix broken links to tools API docs. --- docs/index.md | 4 ++-- docs/redirects.json | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 81e760faddb..50d5f7ad468 100644 --- a/docs/index.md +++ b/docs/index.md @@ -111,8 +111,8 @@ Deep technical documentation and API specifications. processes memory from various sources. - **[Policy engine](./reference/policy-engine.md):** Fine-grained execution control. -- **[Tools API](./reference/tools-api.md):** The API for defining and using - tools. +- **[Tools reference](./reference/tools.md):** Information on how tools are + defined, registered, and used. ## Resources diff --git a/docs/redirects.json b/docs/redirects.json index 5183d0d476a..598f42cccf2 100644 --- a/docs/redirects.json +++ b/docs/redirects.json @@ -8,7 +8,8 @@ "/docs/core/concepts": "/docs", "/docs/core/memport": "/docs/reference/memport", "/docs/core/policy-engine": "/docs/reference/policy-engine", - "/docs/core/tools-api": "/docs/reference/tools-api", + "/docs/core/tools-api": "/docs/reference/tools", + "/docs/reference/tools-api": "/docs/reference/tools", "/docs/faq": "/docs/resources/faq", "/docs/get-started/configuration": "/docs/reference/configuration", "/docs/get-started/configuration-v1": "/docs/reference/configuration", From 50e5b3da3761dcb62a1d4a49dcd7fac54d9d12b0 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Tue, 24 Feb 2026 17:35:22 -0800 Subject: [PATCH 08/12] Docs: Fix broken links related to tools-api.md --- docs/hooks/reference.md | 4 ++-- docs/reference/tools.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/hooks/reference.md b/docs/hooks/reference.md index 9b7226ac05b..445035b1aaf 100644 --- a/docs/hooks/reference.md +++ b/docs/hooks/reference.md @@ -82,8 +82,8 @@ For `BeforeTool` and `AfterTool` events, the `matcher` field in your settings is compared against the name of the tool being executed. - **Built-in Tools**: You can match any built-in tool (e.g., `read_file`, - `run_shell_command`). See the [Tools Reference](/docs/tools) for a full list - of available tool names. + `run_shell_command`). See the [Tools Reference](/docs/reference/tools) for a + full list of available tool names. - **MCP Tools**: Tools from MCP servers follow the naming pattern `mcp____`. - **Regex Support**: Matchers support regular expressions (e.g., diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 6c2b212c745..3d06720eb6d 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -103,4 +103,4 @@ You can extend Gemini CLI with custom tools by configuring - Learn how to [Set up an MCP server](../tools/mcp-server.md). - Explore [Agent Skills](../cli/skills.md) for specialized expertise. -- See the [Command reference](../cli/commands.md) for slash commands. +- See the [Command reference](./commands.md) for slash commands. From 0a5711689c301085a6abb1e3d5d470200a4101f3 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Mon, 2 Mar 2026 13:11:26 -0800 Subject: [PATCH 09/12] Update docs/reference/tools.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/reference/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index 3d06720eb6d..f6a44e7fca5 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -74,7 +74,7 @@ function. | File System | [`list_directory`](../tools/file-system.md) | `Read` | Lists the names of files and subdirectories within a specified path.

**Parameters:** `dir_path`, `ignore`, `file_filtering_options` | | File System | [`read_file`](../tools/file-system.md) | `Read` | Reads the content of a specific file. Supports text, images, audio, and PDF.

**Parameters:** `file_path`, `offset`, `limit` | | File System | [`read_many_files`](../tools/file-system.md) | `Read` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt.

**Parameters:** `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | -| File System | [`replace`](../tools/file-system.md) | `Edit` | Performs precise text replacement within a file. Requires manual confirmation.

**Parameters:** `file_path`, `old_string`, `new_string`, `expected_replacements`, `instruction` | +| File System | [`replace`](../tools/file-system.md) | `Edit` | Performs precise text replacement within a file. Requires manual confirmation.

**Parameters:** `file_path`, `instruction`, `old_string`, `new_string`, `allow_multiple` | | File System | [`write_file`](../tools/file-system.md) | `Edit` | Creates or overwrites a file with new content. Requires manual confirmation.

**Parameters:** `file_path`, `content` | | Interaction | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog.

**Parameters:** `questions` | | Interaction | [`write_todos`](../tools/todos.md) | `Other` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you.

**Parameters:** `todos` | From 43c08b823828180c440d47851344051220c57e2a Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Mon, 2 Mar 2026 13:11:55 -0800 Subject: [PATCH 10/12] Update docs/reference/tools.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/reference/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index f6a44e7fca5..a1c344d3c3b 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -85,7 +85,7 @@ function. | Planning | [`exit_plan_mode`](../tools/planning.md) | `Plan` | Finalizes a plan, presents it for review, and requests approval to start implementation.

**Parameters:** `plan` | | System | `complete_task` | `Other` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user.

**Parameters:** `result` | | Web | [`google_web_search`](../tools/web-search.md) | `Search` | Performs a Google Search to find up-to-date information.

**Parameters:** `query` | -| Web | [`web_fetch`](../tools/web-fetch.md) | `Fetch` | Retrieves and processes content from specific URLs.

**Parameters:** `prompt` | +| Web | [`web_fetch`](../tools/web-fetch.md) | `Fetch` | Retrieves and processes content from specific URLs. **Warning:** This tool can access local and private network addresses (e.g., localhost), which may pose a security risk if used with untrusted prompts.

**Parameters:** `prompt` | ## Under the hood From 0b3e7c77571da1001761550a0628418c582a72de Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Mon, 2 Mar 2026 13:12:18 -0800 Subject: [PATCH 11/12] Update docs/reference/tools.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- docs/reference/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index a1c344d3c3b..f06c9e03495 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -72,7 +72,7 @@ function. | File System | [`glob`](../tools/file-system.md) | `Search` | Finds files matching specific glob patterns across the workspace.

**Parameters:** `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | | File System | [`grep_search`](../tools/file-system.md) | `Search` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`.

**Parameters:** `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | | File System | [`list_directory`](../tools/file-system.md) | `Read` | Lists the names of files and subdirectories within a specified path.

**Parameters:** `dir_path`, `ignore`, `file_filtering_options` | -| File System | [`read_file`](../tools/file-system.md) | `Read` | Reads the content of a specific file. Supports text, images, audio, and PDF.

**Parameters:** `file_path`, `offset`, `limit` | +| File System | [`read_file`](../tools/file-system.md) | `Read` | Reads the content of a specific file. Supports text, images, audio, and PDF.

**Parameters:** `file_path`, `start_line`, `end_line` | | File System | [`read_many_files`](../tools/file-system.md) | `Read` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt.

**Parameters:** `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | | File System | [`replace`](../tools/file-system.md) | `Edit` | Performs precise text replacement within a file. Requires manual confirmation.

**Parameters:** `file_path`, `instruction`, `old_string`, `new_string`, `allow_multiple` | | File System | [`write_file`](../tools/file-system.md) | `Edit` | Creates or overwrites a file with new content. Requires manual confirmation.

**Parameters:** `file_path`, `content` | From de339baab5b9d6ecc145a3b7611a660dff9d1fa2 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Mon, 2 Mar 2026 13:51:00 -0800 Subject: [PATCH 12/12] Docs: Update tools reference - formatting. --- docs/reference/tools.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/reference/tools.md b/docs/reference/tools.md index f06c9e03495..e1a0958866f 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -66,26 +66,26 @@ details. The following table lists all available tools, categorized by their primary function. -| Category | Tool | Kind | Description | -| :---------- | :----------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Execution | [`run_shell_command`](../tools/shell.md) | `Execute` | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation.

**Parameters:** `command`, `description`, `dir_path`, `is_background` | -| File System | [`glob`](../tools/file-system.md) | `Search` | Finds files matching specific glob patterns across the workspace.

**Parameters:** `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | -| File System | [`grep_search`](../tools/file-system.md) | `Search` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`.

**Parameters:** `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | -| File System | [`list_directory`](../tools/file-system.md) | `Read` | Lists the names of files and subdirectories within a specified path.

**Parameters:** `dir_path`, `ignore`, `file_filtering_options` | -| File System | [`read_file`](../tools/file-system.md) | `Read` | Reads the content of a specific file. Supports text, images, audio, and PDF.

**Parameters:** `file_path`, `start_line`, `end_line` | -| File System | [`read_many_files`](../tools/file-system.md) | `Read` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt.

**Parameters:** `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | -| File System | [`replace`](../tools/file-system.md) | `Edit` | Performs precise text replacement within a file. Requires manual confirmation.

**Parameters:** `file_path`, `instruction`, `old_string`, `new_string`, `allow_multiple` | -| File System | [`write_file`](../tools/file-system.md) | `Edit` | Creates or overwrites a file with new content. Requires manual confirmation.

**Parameters:** `file_path`, `content` | -| Interaction | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog.

**Parameters:** `questions` | -| Interaction | [`write_todos`](../tools/todos.md) | `Other` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you.

**Parameters:** `todos` | -| Memory | [`activate_skill`](../tools/activate-skill.md) | `Other` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory.

**Parameters:** `name` | -| Memory | [`get_internal_docs`](../tools/internal-docs.md) | `Think` | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities.

**Parameters:** `path` | -| Memory | [`save_memory`](../tools/memory.md) | `Think` | Persists specific facts and project details to your `GEMINI.md` file to retain context.

**Parameters:** `fact` | -| Planning | [`enter_plan_mode`](../tools/planning.md) | `Plan` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes.

**Parameters:** `reason` | -| Planning | [`exit_plan_mode`](../tools/planning.md) | `Plan` | Finalizes a plan, presents it for review, and requests approval to start implementation.

**Parameters:** `plan` | -| System | `complete_task` | `Other` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user.

**Parameters:** `result` | -| Web | [`google_web_search`](../tools/web-search.md) | `Search` | Performs a Google Search to find up-to-date information.

**Parameters:** `query` | -| Web | [`web_fetch`](../tools/web-fetch.md) | `Fetch` | Retrieves and processes content from specific URLs. **Warning:** This tool can access local and private network addresses (e.g., localhost), which may pose a security risk if used with untrusted prompts.

**Parameters:** `prompt` | +| Category | Tool | Kind | Description | +| :---------- | :----------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Execution | [`run_shell_command`](../tools/shell.md) | `Execute` | Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation.

**Parameters:** `command`, `description`, `dir_path`, `is_background` | +| File System | [`glob`](../tools/file-system.md) | `Search` | Finds files matching specific glob patterns across the workspace.

**Parameters:** `pattern`, `dir_path`, `case_sensitive`, `respect_git_ignore`, `respect_gemini_ignore` | +| File System | [`grep_search`](../tools/file-system.md) | `Search` | Searches for a regular expression pattern within file contents. Legacy alias: `search_file_content`.

**Parameters:** `pattern`, `dir_path`, `include`, `exclude_pattern`, `names_only`, `max_matches_per_file`, `total_max_matches` | +| File System | [`list_directory`](../tools/file-system.md) | `Read` | Lists the names of files and subdirectories within a specified path.

**Parameters:** `dir_path`, `ignore`, `file_filtering_options` | +| File System | [`read_file`](../tools/file-system.md) | `Read` | Reads the content of a specific file. Supports text, images, audio, and PDF.

**Parameters:** `file_path`, `start_line`, `end_line` | +| File System | [`read_many_files`](../tools/file-system.md) | `Read` | Reads and concatenates content from multiple files. Often triggered by the `@` symbol in your prompt.

**Parameters:** `include`, `exclude`, `recursive`, `useDefaultExcludes`, `file_filtering_options` | +| File System | [`replace`](../tools/file-system.md) | `Edit` | Performs precise text replacement within a file. Requires manual confirmation.

**Parameters:** `file_path`, `instruction`, `old_string`, `new_string`, `allow_multiple` | +| File System | [`write_file`](../tools/file-system.md) | `Edit` | Creates or overwrites a file with new content. Requires manual confirmation.

**Parameters:** `file_path`, `content` | +| Interaction | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog.

**Parameters:** `questions` | +| Interaction | [`write_todos`](../tools/todos.md) | `Other` | Maintains an internal list of subtasks. The model uses this to track its own progress and display it to you.

**Parameters:** `todos` | +| Memory | [`activate_skill`](../tools/activate-skill.md) | `Other` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory.

**Parameters:** `name` | +| Memory | [`get_internal_docs`](../tools/internal-docs.md) | `Think` | Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities.

**Parameters:** `path` | +| Memory | [`save_memory`](../tools/memory.md) | `Think` | Persists specific facts and project details to your `GEMINI.md` file to retain context.

**Parameters:** `fact` | +| Planning | [`enter_plan_mode`](../tools/planning.md) | `Plan` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes.

**Parameters:** `reason` | +| Planning | [`exit_plan_mode`](../tools/planning.md) | `Plan` | Finalizes a plan, presents it for review, and requests approval to start implementation.

**Parameters:** `plan` | +| System | `complete_task` | `Other` | Finalizes a subagent's mission and returns the result to the parent agent. This tool is not available to the user.

**Parameters:** `result` | +| Web | [`google_web_search`](../tools/web-search.md) | `Search` | Performs a Google Search to find up-to-date information.

**Parameters:** `query` | +| Web | [`web_fetch`](../tools/web-fetch.md) | `Fetch` | Retrieves and processes content from specific URLs. **Warning:** This tool can access local and private network addresses (e.g., localhost), which may pose a security risk if used with untrusted prompts.

**Parameters:** `prompt` | ## Under the hood