diff --git a/README.md b/README.md index 02dd4988f0..46aa6604c2 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,8 +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/reference/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 44d8ba9467..39c0f7c5c1 100644 --- a/docs/cli/enterprise.md +++ b/docs/cli/enterprise.md @@ -244,7 +244,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](../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` @@ -308,8 +308,8 @@ unintended tool execution. ## Managing custom tools (MCP servers) If your organization uses custom tools via -[Model-Context Protocol (MCP) servers](../reference/tools-api.md), it is crucial -to understand how server configurations are managed to apply security policies +[Model-Context Protocol (MCP) servers](../tools/mcp-server.md), it is crucial to +understand how server configurations are managed to apply security policies effectively. ### How MCP server configurations are merged diff --git a/docs/core/index.md b/docs/core/index.md index 53aa647dc2..adf186116f 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](../reference/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](../reference/memport.md):** Documentation for the modular GEMINI.md import feature using @file.md syntax. - **[Policy Engine](../reference/policy-engine.md):** Use the Policy Engine for diff --git a/docs/hooks/reference.md b/docs/hooks/reference.md index 9b7226ac05..445035b1aa 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/index.md b/docs/index.md index 3ccaf3b797..af1915bb8f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -108,8 +108,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 5183d0d476..598f42cccf 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", diff --git a/docs/reference/tools-api.md b/docs/reference/tools-api.md deleted file mode 100644 index 91fae3f720..0000000000 --- a/docs/reference/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 0000000000..e1a0958866 --- /dev/null +++ b/docs/reference/tools.md @@ -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.

**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 + +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. diff --git a/docs/sidebar.json b/docs/sidebar.json index 4d6d9df10a..000f571077 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -188,7 +188,7 @@ "slug": "docs/reference/memport" }, { "label": "Policy engine", "slug": "docs/reference/policy-engine" }, - { "label": "Tools API", "slug": "docs/reference/tools-api" } + { "label": "Tools reference", "slug": "docs/reference/tools" } ] } ] diff --git a/docs/tools/index.md b/docs/tools/index.md deleted file mode 100644 index 6bdf298fea..0000000000 --- a/docs/tools/index.md +++ /dev/null @@ -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.