Chapter 7: The 8 Built-in Tools — What Each One Does

By the end of this chapter, you will know exactly what each of the eight built-in agent tools does, when to use each one, and how to selectively enable or disable them to keep your agent focused and secure.

The Big Idea

Claude can reason about almost anything. But without tools, it can only speak. The eight built-in tools are what transform Claude from a language model into an agent that can actually do things: manipulate files, execute code, search the internet, and read from any URL.

These tools come packaged together under a single toolset identifier — agent_toolset_20260401 — and are all enabled by default when you include the toolset in your agent configuration. You don't have to configure each one individually unless you want to restrict or customize them.

From the tools documentation:

Understanding these eight tools is the foundation for designing good agents. You'll choose which to enable based on what your agent needs to do and what risks you're comfortable with.

The Analogy

Imagine outfitting a contractor's tool belt before they start a job.

bash is the power drill — the most powerful and versatile tool, capable of almost anything, but also the one requiring the most care. read and write are the tape measure and pencil — basic, constantly needed, low risk. edit is the correction fluid — for precise, targeted changes. glob and grep are the blueprint index and highlighter — for finding things fast. web_fetch and web_search are the phone — for looking things up in the outside world.

Not every job needs every tool. A task that only involves processing local files doesn't need the phone. A task that requires no file manipulation doesn't need the pencil. Fit the tool belt to the job, and your agent will use its context window more efficiently and be less likely to reach for tools inappropriately.

How It Actually Works

1. bash — The Power Tool

bash executes shell commands in a persistent shell session within the container. It's the most capable tool in the set because it can do almost anything: install packages, run scripts, call command-line utilities, manipulate processes, pipe output between tools.

In practice, bash is how Claude:

• Runs Python scripts it has written
• Compiles code, runs tests, or checks test output
• Calls git commands
• Executes build systems (make, npm, cargo)
• Does anything that requires combining multiple operations

Because bash can execute arbitrary code, it's also the tool that requires the most thoughtful permission policy. For agents that don't need to execute arbitrary shell commands (data transformation, document generation, web research), you may want to keep bash set to always_ask while leaving other tools on always_allow. Chapter 8 covers this in detail.

2. read — Reading Files

read reads a file from the container's local filesystem and returns its contents to Claude. Claude can read any file at any path in the container — source code, configuration files, data files, logs.

This is different from files you mount at session creation (which are placed in a specific path in the container). read can read any file that exists in the container, including files created by a previous tool call in the same session.

Common uses:

• Reading code before editing it
• Reading configuration files to understand the current state
• Reading test output to understand what failed
• Reading documentation or README files in a mounted repository

3. write — Writing Files

write writes content to a file on the container's local filesystem. It creates the file if it doesn't exist, and overwrites it if it does. Parent directories are created automatically.

This is Claude's primary mechanism for producing persistent output:

• Writing code it has generated
• Writing reports or analysis documents
• Writing configuration files
• Saving intermediate work products

Files written with write persist within the session's container. To retrieve them after the session completes, they need to be written to /mnt/session/outputs/ — this is the designated output path for files you want to download via the Files API after the session ends.

4. edit — Targeted File Changes

edit performs string replacement in a file — it finds an exact string in the file and replaces it with a new one. It's designed for surgical edits: changing a specific function, updating a configuration value, fixing a specific bug.

edit is preferable to write for modifications because it:

• Preserves all file content except the targeted change
• Makes the intent of the change explicit (what was replaced, what it became)
• Reduces the risk of accidentally overwriting content

For large codebases, having Claude use edit for targeted changes produces more reliable results than rewriting entire files with write.

5. glob — File Pattern Matching

glob finds files matching a pattern. It works like the find or ls command with wildcards — **/*.py finds all Python files recursively, src/*.ts finds all TypeScript files in a specific directory.

glob is how Claude explores an unfamiliar codebase:

• "Find all Python test files"
• "Find all configuration files in the root directory"
• "Find all markdown documentation"

In agent workflows that start with a mounted repository or a complex directory structure, glob is usually one of the first tools Claude reaches for.

6. grep — Text Search

grep searches file contents using regex patterns. It's the equivalent of a code-aware "find in files" — searching for function names, error messages, specific strings, or patterns across many files at once.

The tools documentation notes that under the hood, ripgrep (rg) is pre-installed in the container — a fast file search tool. grep leverages this for speed.

Common uses:

• Finding where a function is defined or called
• Locating all occurrences of an error message
• Searching for a specific configuration value across a codebase
• Identifying all files that import a specific module

7. web_fetch — Fetch a URL

web_fetch retrieves the content of a specific URL. Claude uses it to read web pages, download documentation, fetch API responses, or retrieve any content available at a known URL.

This is different from web_search — web_fetch requires knowing the URL; it doesn't discover URLs. Use it when you have a specific resource in mind (a documentation page, an API endpoint, a file hosted online).

Important notes:

• The networking configuration in the environment controls what URLs the container can reach. web_fetch is not subject to the same network restrictions as the container's bash commands — the tools documentation notes that web_search and web_fetch's allowed domains are not impacted by the container's networking field configuration.
• Claude can parse the returned content and extract relevant information from it.

8. web_search — Search the Web

web_search searches the web and returns results. It's how Claude finds current information, discovers resources, and researches topics when it doesn't have a specific URL.

This is Claude's primary mechanism for accessing information beyond what it was trained on: current prices, recent news, updated documentation, anything that might have changed since the model's training cutoff.

For agents that need to produce current, accurate information (market research, news analysis, technical documentation lookup), web_search is often the most important tool.

Enabling the Toolset

To enable all eight tools, include the toolset in your agent's tools array:

# Enable the full toolset (all 8 tools enabled by default)
type: agent_toolset_20260401

Disabling Specific Tools

To disable specific tools while keeping others, use the configs array:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

(Tools documentation)

This is useful for agents that should work only with local files (disable web tools) or should never execute arbitrary shell commands (disable bash).

The Whitelist Pattern — Start with Everything Off

For maximum control, start with everything disabled and explicitly enable only what you need:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}

(Tools documentation)

This is the recommended approach for production agents where you want to minimize the attack surface and keep the agent focused on what it actually needs.

YAML Agent Creation with a Disabled Tool

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-7
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML

(Tools documentation)

Choosing Tools for Common Agent Types

Chapter Recap

• The eight built-in tools cover: file system operations (read, write, edit, glob, grep), shell execution (bash), and web access (web_fetch, web_search). All are enabled by default when you include agent_toolset_20260401.
• Disable tools your agent doesn't need. Use the configs array to disable specific tools, or the whitelist pattern (default_config: enabled: false) to start with everything off and explicitly opt in.
• bash is the most powerful tool and the one requiring the most permission thought. read/write are the workhorses. web_search/web_fetch are the windows to the outside world. Choose your tool belt based on the job.