gemini-cli/docs/reference/tools.md

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 guide.
• Trusted folders: You can configure which directories allow the model to use system tools. For more details, see the Trusted folders 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 (@): 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 (!): 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 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 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	Execute	Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation. Parameters: command, description, dir_path, is_background
File System	glob	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	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	Read	Lists the names of files and subdirectories within a specified path. Parameters: dir_path, ignore, file_filtering_options
File System	read_file	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	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	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	Edit	Creates or overwrites a file with new content. Requires manual confirmation. Parameters: file_path, content
Interaction	ask_user	Communicate	Requests clarification or missing information via an interactive dialog. Parameters: questions
Interaction	write_todos	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	Other	Loads specialized procedural expertise for specific tasks from the .gemini/skills directory. Parameters: name
Memory	get_internal_docs	Think	Accesses Gemini CLI's own documentation to provide more accurate answers about its capabilities. Parameters: path
Memory	save_memory	Think	Persists specific facts and project details to your GEMINI.md file to retain context. Parameters: fact
Planning	enter_plan_mode	Plan	Switches the CLI to a safe, read-only "Plan Mode" for researching complex changes. Parameters: reason
Planning	exit_plan_mode	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	Search	Performs a Google Search to find up-to-date information. Parameters: query
Web	web_fetch	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.
• Explore Agent Skills for specialized expertise.
• See the Command reference for slash commands.