Skip to main content
Gemini CLI uses tools to extend the model’s capabilities beyond text generation. Tools allow the AI to read files, execute commands, search the web, and perform actions on your behalf.

​
How Tools Work

You use tools indirectly through natural language prompts. The model decides when tools are needed and requests them automatically.
1

You provide a prompt

Enter a request like “Update the README with installation instructions” or use special syntax like @package.json.
2

Model analyzes the request

The Gemini model determines if tools are needed to fulfill your request (e.g., reading the current README, writing the updated content).
3

Tool validation

The CLI validates tool parameters and checks security settings to ensure the operation is safe.
4

User confirmation

For sensitive operations (file writes, shell commands), you’re prompted to approve the action with a preview of changes.
5

Tool execution

The approved tool executes and returns results to the model.
6

Model responds

The model uses tool results to generate a final, grounded answer.

​
Tool Categories

Gemini CLI tools fall into three main categories:

User-Triggered

Tools you activate explicitly with special syntax

Model-Triggered

Tools the model requests automatically when needed

Information

Tools for accessing external data and services

​
User-Triggered Tools

You can directly trigger these tools using special syntax in your prompts.

​
File Access (@)

Include file or directory contents in your prompt using the @ symbol. Syntax: 
@path/to/file.js
@src/components/
Examples: 
# Include a single file
@package.json explain the dependencies

# Include a directory
@src/utils/ what utility functions are available?

# Multiple files
@src/index.js @src/config.js how are these files connected?
This triggers the read_many_files tool, which reads and includes the content in your prompt context.

​
Shell Commands (!)

Execute shell commands directly using the ! symbol. Syntax: 
!command [arguments]
Examples: 
# Check git status
!git status

# Run tests
!npm test

# List files
!ls -la src/
Shell commands require confirmation before execution. Always review the command carefully before approving.

​
Model-Triggered Tools

The model automatically requests these tools when needed to fulfill your requests. You don’t call them manually.

​
File Management Tools

These tools let the model explore and modify your local codebase.
Lists files and subdirectories within a specified path.Parameters:
  • dir_path - Absolute or relative path to directory
  • ignore - Optional glob patterns to exclude
  • file_filtering_options - Optional .gitignore and .geminiignore compliance
When used:
  • “What files are in the src directory?”
  • “Show me the project structure”
  • “List all components”
Confirmation: No
Reads and returns the content of a specific file. Supports text, images, audio, and PDF.Parameters:
  • file_path - Path to the file
  • offset - Optional start line (0-based)
  • limit - Optional maximum lines to read
When used:
  • “Read the config file”
  • “What’s in index.js?”
  • “Show me the README”
Confirmation: No
Writes content to a file, creating it if it doesn’t exist or overwriting if it does.Parameters:
  • file_path - Path to the file
  • content - Data to write
When used:
  • “Create a new component file”
  • “Update the package.json”
  • “Write this config to settings.json”
Confirmation: ✅ Required - Shows diff preview
Finds files matching glob patterns across your workspace.Parameters:
  • pattern - Glob pattern (e.g., *.py, src/**/*.js)
  • path - Optional directory to search (defaults to root)
  • case_sensitive - Optional case sensitivity (defaults to false)
  • respect_git_ignore - Optional .gitignore compliance (defaults to true)
When used:
  • “Find all TypeScript files”
  • “Locate test files”
  • “Show me all markdown documents”
Confirmation: No
Searches for regex patterns within file contents using grep or ripgrep.Parameters:
  • pattern - Regular expression to search for
  • path - Optional directory to search
  • include - Optional glob pattern to filter files
When used:
  • “Find all TODO comments”
  • “Search for function definitions”
  • “Where is this variable used?”
Confirmation: No
Performs precise text replacements within a file.Parameters:
  • file_path - Path to the file
  • instruction - Semantic description of the change
  • old_string - Exact text to find
  • new_string - Exact text to replace with
  • allow_multiple - Optional flag to replace all occurrences
When used:
  • “Update the API endpoint URL”
  • “Change the port number”
  • “Rename this function”
Confirmation: ✅ Required - Shows diff preview

​
Agent Coordination Tools

These tools help the model plan tasks and interact with you.
Prompts you for clarification or missing information through an interactive dialog.When used:
  • Model needs more context
  • Ambiguous requirements
  • Missing configuration details
Confirmation: Interactive response required
Saves important facts to your long-term memory (GEMINI.md file).When used:
  • You ask to remember something
  • Important project conventions noted
  • Persistent preferences established
Confirmation: Yes, for file write
Creates and manages a list of subtasks for complex plans.When used:
  • Breaking down large tasks
  • Tracking multi-step operations
  • Planning complex changes
Confirmation: No
Loads specialized procedural expertise for specific tasks.When used:
  • Domain-specific workflows needed
  • Specialized procedures required
  • Expert guidance necessary
Confirmation: No
Automates web browser tasks through the accessibility tree (experimental).When used:
  • Filling web forms
  • Navigating websites
  • Extracting web page data
Requirements: Chrome 144+, must be enabled in settingsConfirmation: Yes, for sensitive actions
Accesses Gemini CLI’s own documentation to answer questions.When used:
  • Questions about CLI features
  • Configuration help needed
  • Command reference required
Confirmation: No

​
Information Gathering Tools

These tools provide access to external data and services.
Retrieves and processes content from specific URLs.Parameters:
  • url - The URL to fetch
  • options - Optional request configuration
When used:
  • “Get content from this URL”
  • “Fetch the API documentation”
  • “Read this blog post”
Confirmation: No (may require for sensitive operations)
Performs Google Search to find up-to-date information.Parameters:
  • query - Search query string
When used:
  • “Search for best practices”
  • “Find recent documentation”
  • “Look up current syntax”
Confirmation: No

​
Security and Confirmation

Safety is a core part of the tool system. Gemini CLI implements several safeguards:

​
User Confirmation

You must manually approve tools that modify files or execute shell commands. 
┌─ write_file ────────────────────────────────────┐
│ Path: src/config.js                             │
│                                                  │
│ + export const API_URL = 'https://api.example'; │
│                                                  │
│ Approve this change? [y/n]                      │
└──────────────────────────────────────────────────┘
Always review confirmation prompts carefully. Verify that:
  • File changes match your intent
  • Shell commands are safe to execute
  • Paths and parameters are correct

​
Sandboxing

You can run tool executions in secure, containerized environments to isolate changes from your host system.

Learn More About Sandboxing

Configure sandboxed execution environments for additional security

​
Trusted Folders

Configure which directories allow the model to use system tools.

Configure Trusted Folders

Set up directory-based execution policies

​
Policy Engine

Use fine-grained control over tool execution with the Policy Engine.

Policy Engine Reference

Define custom rules for tool execution

​
Extending with MCP Servers

You can extend Gemini CLI with custom tools using Model Context Protocol (MCP) servers. Example MCP integrations: 
# GitHub operations
> @github List my open pull requests

# Slack integration
> @slack Send a summary to #dev channel

# Database queries
> @database Find inactive users

MCP Server Integration

Learn how to configure and use MCP servers

​
Tool Development

You can create custom tools for Gemini CLI.

Tools API Reference

Build your own tools with the Tools API

​
Best Practices

Clear prompts help the model select the right tools:✅ Good: “Update the API endpoint in config.js from localhost to production URL”❌ Vague: “Fix the config”
Always verify:
  • File paths are correct
  • Changes match your intent
  • Commands are safe to execute
Don’t approve without reading!
Include relevant files in your prompt:
@src/api/client.js @src/config.js 
Update the API client to use the config settings
Instead of repeating tool usage preferences, add them to your GEMINI.md:
## Tool Preferences
- Always run tests after modifying code
- Use TypeScript for new files
- Follow existing code style

​
Troubleshooting

Common causes:
  • Insufficient permissions
  • File or directory doesn’t exist
  • Not in a trusted folder
Solutions:
  • Check file permissions
  • Verify paths are correct
  • Configure trusted folders
Common causes:
  • Prompt is too vague
  • Tool not needed for the task
  • Tool disabled in settings
Solutions:
  • Be more specific in your request
  • Explicitly mention what you want (e.g., “read the file and…”)
  • Check tool configuration in settings
Common causes:
  • Security settings require confirmation
  • Operating in untrusted directory
Solutions:
  • Add directory to trusted folders
  • Adjust confirmation settings
  • Use sandbox mode for experimentation

​
Next Steps

How It Works

Understand the tool orchestration flow

Context Management

Learn how to provide instructions with GEMINI.md

File Management Tutorial

Hands-on guide to working with files

Shell Commands Tutorial

Master terminal integration

Build docs developers (and LLMs) love

Get started for freeTalk to us