Tools 101

Tier 1 · Fundamentals 8 min read

In the Tier 0 articles, you saw that a harness gives the model tools — concrete actions it can call. This page goes one level deeper: what are the built-in tools, how does the agent decide which to use, and what does the result look like?

The built-in tools

Claude Code ships with five core tools. You don’t install or configure them — they’re always available:

Read

Reads a file from the filesystem and returns its contents to the agent. The agent sees the file content with line numbers, which it uses to make precise edits.

Read("/Users/jd/clawd/projects/analytics-suite/state/issues.yaml")

The result is the file’s full text (or a slice, if the agent requests a line range). This is how the agent “knows” what’s in your code before it edits.

Edit

Makes a targeted replacement in a file. The agent specifies the exact text to find and the text to replace it with. Because it’s a string replace rather than a full rewrite, only the changed lines touch the file.

Edit is the default choice for modifying existing files — it sends only the diff, not the whole file back, which is efficient in both tokens and risk.

Write

Writes a complete file to disk, overwriting it if it exists. The agent uses Write when creating a new file or when an Edit would be too fragmented to express cleanly (e.g., the whole structure has changed).

Bash

Runs a shell command and returns the output. This is the most powerful tool: it can run tests, install packages, call APIs, restart processes, read environment variables, and do anything else a terminal can do.

# Example: the agent runs the test suite and reads the result
bash pytest -q tests/unit/

Bash is also where things can go wrong. A careless rm -rf, a git push --force, a database migration that drops a table — these all route through Bash. This is why the allow/deny prompt system exists (covered in Tier 0 / Permissions) and why your CLAUDE.md should list the commands that require confirmation.

Grep

Searches file contents across a directory tree. The agent uses this to find a function, a class, a config key, or a pattern across hundreds of files without reading each one individually.

# Grep for all uses of a function before editing it
grep -r "fulfill_drain" ~/clawd/projects/agent-tree-merch/

In practice, Grep is the agent’s “where does this live?” tool. It narrows the search space before Read opens specific files.

How the agent picks tools

The agent chooses tools based on what it needs to do next, reasoning through the task the same way a developer would:

“I need to understand what’s in this file” → Read.
“I need to find where something is defined” → Grep, then Read.
“I need to change one thing in a file I’ve already read” → Edit.
“I need to create a new file” → Write.
“I need to run the tests / install a package / call an API” → Bash.
“I need to do something complex that spans multiple files and commands” → a sequence of the above, in order.

The agent can and regularly does call multiple tools in a single turn. It might: Grep to find the relevant file → Read the file → Edit it → Bash to run pytest -q → check the output and, if tests pass, Bash again to commit.

What a tool result looks like

When you watch a Claude Code session, you see the tool calls and their results interleaved with the agent’s thinking. Each tool call produces a result that goes back into the context window for the agent to act on. For example:

[Tool: Read]
→ File: tests/test_merch.py (lines 1–50)
   1  import pytest
   2  from agents.merch.ip_safety import check_design
   ...

[Tool: Edit]
→ Applied: changed "assert result == True" → "assert result is True" at line 34
→ File saved.

[Tool: Bash]
→ Command: pytest tests/test_merch.py -q
→ Output: 50 passed in 1.3s

Each result is evidence the agent reads before deciding what to do next. This is why reading the output (covered in Tier 0 / Reading the Output) matters: the chain of tool calls is the agent’s work, and you can follow exactly what it’s doing and why.

Tool use is the signal

One finding from running agents on real work: the ability to use tools well is what separates a capable agent from an expensive chatbot. A model that explains how to fix a bug is a chatbot. A model that Greps to find the file, Reads the function, Edits the fix, runs pytest, and confirms the test passes is an agent that closed the loop.

The MBA analytics suite on this system scored 30/30 on a real exam — not because the model was smarter than others, but because it could use tools: fetch the data, run the regression, read the output, and correct the approach when the first pass was wrong.

Next: Prompting the CLI Well — how to ask the agent for goals instead of steps, and why the framing of a request determines the quality of the result.