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