MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Create tools reference (#19470)

Browse Source 
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
This commit is contained in:
Jenna Inouye
2026-03-04 12:16:33 -08:00
committed by GitHub
parent 1c92824636
commit 29b3aa860c
10 changed files with 120 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@@ -301,7 +301,7 @@ gemini
### Tools & Extensions ### 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) - [File System Operations](./docs/tools/file-system.md)
- [Shell Commands](./docs/tools/shell.md) - [Shell Commands](./docs/tools/shell.md)
- [Web Fetch & Search](./docs/tools/web-fetch.md) - [Web Fetch & Search](./docs/tools/web-fetch.md)
@@ -323,8 +323,7 @@ gemini
- [**Enterprise Guide**](./docs/cli/enterprise.md) - Deploy and manage in a - [**Enterprise Guide**](./docs/cli/enterprise.md) - Deploy and manage in a
corporate environment. corporate environment.
- [**Telemetry & Monitoring**](./docs/cli/telemetry.md) - Usage tracking. - [**Telemetry & Monitoring**](./docs/cli/telemetry.md) - Usage tracking.
- [**Tools API Development**](./docs/reference/tools-api.md) - Create custom - [**Tools reference**](./docs/reference/tools.md) - Built-in tools overview.
tools.
- [**Local development**](./docs/local-development.md) - Local development - [**Local development**](./docs/local-development.md) - Local development
tooling. tooling.

6
docs/cli/enterprise.md
View File

@@ -244,7 +244,7 @@ gemini
You can significantly enhance security by controlling which tools the 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 model can use. This is achieved through the `tools.core` setting and the
[Policy Engine](../reference/policy-engine.md). For a list of available tools, [Policy Engine](../reference/policy-engine.md). For a list of available tools,
see the [Tools documentation](../tools/index.md). see the [Tools reference](../reference/tools.md).
### Allowlisting with `coreTools` ### Allowlisting with `coreTools`
@@ -308,8 +308,8 @@ unintended tool execution.
## Managing custom tools (MCP servers) ## Managing custom tools (MCP servers)
If your organization uses custom tools via If your organization uses custom tools via
[Model-Context Protocol (MCP) servers](../reference/tools-api.md), it is crucial [Model-Context Protocol (MCP) servers](../tools/mcp-server.md), it is crucial to
to understand how server configurations are managed to apply security policies understand how server configurations are managed to apply security policies
effectively. effectively.
### How MCP server configurations are merged ### How MCP server configurations are merged

4
docs/core/index.md
View File

@@ -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 - **[Sub-agents (experimental)](./subagents.md):** Learn how to create and use
specialized sub-agents for complex tasks. specialized sub-agents for complex tasks.
- **[Core tools API](../reference/tools-api.md):** Information on how tools are - **[Core tools reference](../reference/tools.md):** Information on how tools
defined, registered, and used by the core. are defined, registered, and used by the core.
- **[Memory Import Processor](../reference/memport.md):** Documentation for the - **[Memory Import Processor](../reference/memport.md):** Documentation for the
modular GEMINI.md import feature using @file.md syntax. modular GEMINI.md import feature using @file.md syntax.
- **[Policy Engine](../reference/policy-engine.md):** Use the Policy Engine for - **[Policy Engine](../reference/policy-engine.md):** Use the Policy Engine for

4
docs/hooks/reference.md
View File

@@ -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. compared against the name of the tool being executed.
- **Built-in Tools**: You can match any built-in tool (e.g., `read_file`, - **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 `run_shell_command`). See the [Tools Reference](/docs/reference/tools) for a
of available tool names. full list of available tool names.
- **MCP Tools**: Tools from MCP servers follow the naming pattern - **MCP Tools**: Tools from MCP servers follow the naming pattern
`mcp__<server_name>__<tool_name>`. `mcp__<server_name>__<tool_name>`.
- **Regex Support**: Matchers support regular expressions (e.g., - **Regex Support**: Matchers support regular expressions (e.g.,

4
docs/index.md
View File

@@ -108,8 +108,8 @@ Deep technical documentation and API specifications.
processes memory from various sources. processes memory from various sources.
- **[Policy engine](./reference/policy-engine.md):** Fine-grained execution - **[Policy engine](./reference/policy-engine.md):** Fine-grained execution
control. control.
- **[Tools API](./reference/tools-api.md):** The API for defining and using - **[Tools reference](./reference/tools.md):** Information on how tools are
tools. defined, registered, and used.
## Resources ## Resources

3
docs/redirects.json
View File

@@ -8,7 +8,8 @@
"/docs/core/concepts": "/docs", "/docs/core/concepts": "/docs",
"/docs/core/memport": "/docs/reference/memport", "/docs/core/memport": "/docs/reference/memport",
"/docs/core/policy-engine": "/docs/reference/policy-engine", "/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/faq": "/docs/resources/faq",
"/docs/get-started/configuration": "/docs/reference/configuration", "/docs/get-started/configuration": "/docs/reference/configuration",
"/docs/get-started/configuration-v1": "/docs/reference/configuration", "/docs/get-started/configuration-v1": "/docs/reference/configuration",

131
docs/reference/tools-api.md
View File

@@ -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.

106
docs/reference/tools.md Normal file
View File

@@ -0,0 +1,106 @@
# 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.
## How to use Gemini CLI's tools
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.
### Automatic execution and security
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
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.
Review confirmation prompts carefully before allowing a tool to execute.
### How to use manually-triggered tools
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
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.
## How to manage tools
Using built-in commands, you can inspect available tools and configure how they
behave.
### Tool discovery
Use the `/tools` command to see what tools are currently active in your session.
- **`/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.<br><br>**Parameters:** `command`, `description`, `dir_path`, `is_background` |
| File System | [`glob`](../tools/file-system.md) | `Search` | Finds files matching specific glob patterns across the workspace.<br><br>**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`.<br><br>**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.<br><br>**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.<br><br>**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.<br><br>**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.<br><br>**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.<br><br>**Parameters:** `file_path`, `content` |
| Interaction | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog.<br><br>**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.<br><br>**Parameters:** `todos` |
| Memory | [`activate_skill`](../tools/activate-skill.md) | `Other` | Loads specialized procedural expertise for specific tasks from the `.gemini/skills` directory.<br><br>**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.<br><br>**Parameters:** `path` |
| Memory | [`save_memory`](../tools/memory.md) | `Think` | Persists specific facts and project details to your `GEMINI.md` file to retain context.<br><br>**Parameters:** `fact` |
| Planning | [`enter_plan_mode`](../tools/planning.md) | `Plan` | Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes.<br><br>**Parameters:** `reason` |
| Planning | [`exit_plan_mode`](../tools/planning.md) | `Plan` | Finalizes a plan, presents it for review, and requests approval to start implementation.<br><br>**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.<br><br>**Parameters:** `result` |
| Web | [`google_web_search`](../tools/web-search.md) | `Search` | Performs a Google Search to find up-to-date information.<br><br>**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.<br><br>**Parameters:** `prompt` |
## Under the hood
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
`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 in
> GitHub.
## 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](./commands.md) for slash commands.

2
docs/sidebar.json
View File

@@ -188,7 +188,7 @@
"slug": "docs/reference/memport" "slug": "docs/reference/memport"
}, },
{ "label": "Policy engine", "slug": "docs/reference/policy-engine" }, { "label": "Policy engine", "slug": "docs/reference/policy-engine" },
{ "label": "Tools API", "slug": "docs/reference/tools-api" } { "label": "Tools reference", "slug": "docs/reference/tools" }
] ]
} }
] ]

105
docs/tools/index.md
View File

@@ -1,105 +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.
- **[Browser agent](../core/subagents.md#browser-agent-experimental)
(`browser_agent`):** Automates web browser tasks through the accessibility
tree.
- **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](../reference/commands.md) for tool-related
slash commands.