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 sections list all available tools, categorized by their primary function. For detailed parameter information, see the linked documentation for each tool.

Execution

Tool	Kind	Description
run_shell_command	Execute	Executes arbitrary shell commands. Supports interactive sessions and background processes. Requires manual confirmation.

File System

Tool	Kind	Description
glob	Search	Finds files matching specific glob patterns across the workspace.
grep_search	Search	Searches for a regular expression pattern within file contents. Legacy alias: search_file_content.
list_directory	Read	Lists the names of files and subdirectories within a specified path.
read_file	Read	Reads the content of a specific file. Supports text, images, audio, and PDF.
read_many_files	Read	Reads and concatenates content from multiple files. Often triggered by the @ symbol in your prompt.
replace	Edit	Performs precise text replacement within a file. Requires manual confirmation.
write_file	Edit	Creates or overwrites a file with new content. Requires manual confirmation.

Interaction

Tool	Kind	Description
ask_user	Communicate	Requests clarification or missing information via an interactive dialog.
write_todos	Other	Maintains an internal list of subtasks. The model uses this to track its own progress.

Task Tracker (Experimental)

Note

This is an experimental feature currently under active development. Enable via experimental.taskTracker.

Tool	Kind	Description
tracker_create_task	Other	Creates a new task in the experimental tracker.
tracker_update_task	Other	Updates an existing task’s status, description, or dependencies.
tracker_get_task	Other	Retrieves the full details of a specific task.
tracker_list_tasks	Other	Lists tasks in the tracker, optionally filtered by status, type, or parent.
tracker_add_dependency	Other	Adds a dependency between two tasks, ensuring topological execution.
tracker_visualize	Other	Renders an ASCII tree visualization of the current task graph.

MCP

Tool	Kind	Description
list_mcp_resources	Search	Lists all available resources exposed by connected MCP servers.
read_mcp_resource	Read	Reads the content of a specific Model Context Protocol (MCP) resource.

Memory

Tool	Kind	Description
activate_skill	Other	Loads specialized procedural expertise from the .gemini/skills directory.
get_internal_docs	Think	Accesses Gemini CLI’s own documentation for accurate answers about its capabilities.

Planning

Tool	Kind	Description
enter_plan_mode	Plan	Switches the CLI to a safe, read-only “Plan Mode” for researching complex changes.
exit_plan_mode	Plan	Finalizes a plan, presents it for review, and requests approval to start implementation.

System

Tool	Kind	Description
complete_task	Other	Finalizes a subagent’s mission and returns the result to the parent agent. This tool is not available to the user.

Task Tracking

Tool	Kind	Description
tracker_add_dependency	Think	Adds a dependency between two existing tasks in the tracker.
tracker_create_task	Think	Creates a new task in the internal tracker to monitor progress.
tracker_get_task	Think	Retrieves the details and current status of a specific tracked task.
tracker_list_tasks	Think	Lists all tasks currently being tracked.
tracker_update_task	Think	Updates the status or details of an existing task.
tracker_visualize	Think	Generates a visual representation of the current task dependency graph.
update_topic	Think	Updates the current topic and status to keep the user informed of progress.

Web

Tool	Kind	Description
google_web_search	Search	Performs a Google Search to find up-to-date information.
web_fetch	Fetch	Retrieves and processes content from specific URLs. Outbound requests are validated against private and reserved IP ranges. In Plan Mode, this tool requires explicit user confirmation.

Tool argument keys

When writing argsPattern rules for the policy engine, you need to know the JSON argument keys for each tool. The following table lists the keys that appear in the JSON representation of each tool’s arguments.

Tool	JSON argument keys
run_shell_command	command, description, dir_path, is_background
glob	pattern, dir_path, case_sensitive, respect_git_ignore, respect_gemini_ignore
grep_search	pattern, dir_path, include_pattern, exclude_pattern, names_only, case_sensitive, fixed_strings, context, after, before, no_ignore, max_matches_per_file, total_max_matches
list_directory	dir_path, ignore, file_filtering_options
read_file	file_path, start_line, end_line
read_many_files	include, exclude, recursive, useDefaultExcludes
write_file	file_path, content
replace	file_path, old_string, new_string, instruction, allow_multiple
ask_user	questions (array of question, header, type, options)
write_todos	todos (array of description, status)
activate_skill	name
get_internal_docs	path
enter_plan_mode	reason
exit_plan_mode	plan_path
tracker_create_task	title, description, type
tracker_update_task	id, title, description, status, dependencies
tracker_get_task	id
tracker_list_tasks	status, type, parentId
tracker_add_dependency	taskId, dependencyId
tracker_visualize	(none)
update_topic	title, summary, strategic_intent
google_web_search	query
web_fetch	prompt

For example, to write a policy rule that blocks any write_file call targeting a .env file, you would match against the file_path key:

[[rule]]
toolName = "write_file"
argsPattern = '"file_path":".*\.env"'
decision = "deny"
priority = 100
denyMessage = "Writing to .env files is not allowed."

For full argument descriptions and types, see the individual tool pages linked in the tables above.

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.