Built-in Tools

Official Exam Guide Objectives

Task 2.5: Select and apply built-in tools (Read, Write, Edit, Bash, Grep, Glob) effectively.

Knowledge of

• Grep for content search (searching file contents for patterns like function names, error messages, or import statements)
• Glob for file path pattern matching (finding files by name or extension patterns)
• Read/Write for full file operations; Edit for targeted modifications using unique text matching
• When Edit fails due to non-unique text matches, using Read + Write as a fallback for reliable file modifications

Skills in

• Selecting Grep for searching code content across a codebase (e.g., finding all callers of a function, locating error messages)
• Selecting Glob for finding files matching naming patterns (e.g., **/*.test.tsx)
• Using Read to load full file contents followed by Write when Edit cannot find unique anchor text
• Building codebase understanding incrementally: starting with Grep to find entry points, then using Read to follow imports and trace flows, rather than reading all files upfront
• Tracing function usage across wrapper modules by first identifying all exported names, then searching for each name across the codebase

What You Need to Know

Six built-in tools cover working with a codebase: Read, Write, Edit, Bash, Grep, and Glob. Each is built for a particular job, and reaching for the wrong one costs time, context, or both. Exam items are constructed around exactly those confusions.

Grep vs Glob: The Core Distinction

Nothing else in this task statement is tested as often. Get it wrong and you'll lose marks.

Grep searches file CONTENTS for patterns. Reach for it whenever the question is about what is written inside files — who calls a function, where an error string is raised, which modules import something, where a variable is assigned.

// Every call site of processLegacyOrder()
Grep: "processLegacyOrder"

// Anywhere a timeout is reported to the user
Grep: "timeout"

// Whoever imports the auth helpers
Grep: "import.*from 'utils/auth'"

Glob matches file PATHS by naming patterns. Reach for it whenever the question is about which files exist — tests, configuration, everything of one extension beneath a directory.

// Every test file, wherever it sits
Glob: "**/*.test.tsx"

// Config, whatever extension it uses
Glob: "**/config.*"

// The MDX under the domains tree
Glob: "content/domains/**/*.mdx"

The distinction in one sentence: Grep finds what is INSIDE files. Glob finds files by their NAMES.

Items are built on the substitution. Sent after function callers, Glob returns nothing useful, because a path never contains a call. Sent after test files, Grep can stumble into a partial answer by matching the word in content — which is worse than failing outright, since a partial answer looks like a working one.

Read, Write, and Edit

Three tools for touching files, each suited to a different situation.

Edit changes one thing, located by matching text you supply exactly. It is quick and it is precise, because nothing outside the matched region is loaded or rewritten.

Edit:
  old_string: "function processOrder(id: string)"
  new_string: "function processOrder(id: string, validate = true)"

When Edit fails: the match has to be unique. Where the text you gave appears more than once, Edit stops rather than guessing which occurrence you meant. That refusal is the feature — a guess would silently modify code you never looked at.

When Edit can't find a unique anchor. The fix per the Edit tool docs is to widen old_string with more surrounding context until it pins down one location, or set replace_all: true if every occurrence genuinely should change. Both keep the operation on Edit and cost almost nothing extra. Read + Write — pulling the entire file in, sending the entire file back — is the last resort. It works, and it spends a whole file's worth of context on what was usually a single line.

The ordering:

1. Try Edit with the shortest anchor that's plausibly unique.
2. If the match is not unique, extend old_string with surrounding lines until exactly one place matches — or set replace_all: true where every occurrence really should change.
3. Reach for Read + Write only once neither of those can single out the target.

Two habits are penalised here, and they are different mistakes. Reaching for Read + Write as the standard way to modify a file wastes context on every edit. Reaching for it the instant Edit reports a non-unique match skips the documented recovery, which was two more words of anchor away.

Incremental Codebase Understanding

The order you explore in matters as much as the tools you explore with, and there is a wrong order.

Wrong: Read all files upfront. Loading everything before you know what is relevant is the single most expensive mistake available. Read a 200-file codebase in full and the context window is gone, spent overwhelmingly on files with no bearing on the task.

Right: Incremental discovery. Start narrow. Expand only as needed.

1. Grep to find entry points. Search the name or message that anchors the investigation. The result tells you which files are worth opening.

2. Read to follow imports and trace flows. With the relevant files identified, read them to understand structure, and follow their imports outward to whatever else is implicated.

3. Grep again to trace usage. A wrapper or re-export found along the way becomes a new search term, revealing consumers the first search could not have matched.

4. Read only what you need. Every file opened should be justified by something the previous step turned up.

The result is understanding built at the cost of the files that mattered, rather than the cost of the repository.

Tracing Function Usage Across Wrapper Modules

A common codebase pattern defeats a single search: a function defined in one module, re-exported through a wrapper, and called everywhere under the wrapper's name. Grep for the original and every one of those consumers is invisible.

The correct approach:

1. Grep for the function definition — locate the module that declares it
2. Read the defining file — note every name under which it leaves that module
3. Grep for each exported name — one search per alias, since each has its own consumers
4. Where a barrel file such as index.ts re-exports it, Grep for the barrel's module name as well, to catch imports written against the barrel rather than the source

Each pass supplies the search terms for the next, which is how indirect consumers surface at all.

The Deprecation Scenario

This one turns up constantly in exam prep: find every file that calls a deprecated function AND the test files that exercise it. The correct sequence:

1. Grep for the function name — finds every file whose contents reference the function, including any tests that import it directly (content search)
2. Glob for sibling test files — finds the test file that pairs with each caller by naming convention, e.g. OrderProcessor.ts → OrderProcessor.test.tsx, even when the test exercises the function indirectly through the source module (path matching)
3. Grep again for wrapper names — when a caller exposes the function through a wrapper (e.g. applyLegacyOrder calls processLegacyOrder internally), Grep for the wrapper name to find tests that cover the function transitively through it

Concretely: the first pass shows OrderProcessor.ts and RefundHandler.ts among the callers. Globbing **/OrderProcessor.test.* and **/RefundHandler.test.* then brings in their paired tests, which matter even though they may never write processLegacyOrder anywhere. And where one of those files re-exposes the function under another name, a third pass on that name finds the tests reaching it indirectly.

Grep, then Glob, then Grep — contents for the direct references, paths for the tests sitting alongside them, contents again for the coverage that arrives through a wrapper. Beginning with Glob inverts it and finds only the tests whose names you could already guess.

Deep Dive

The built-in roster is bigger than the six this lesson names

This task statement names six built-ins (Read, Write, Edit, Bash, Grep, Glob), but the documented roster is larger. The Agent SDK overview lists built-in tools as covering "Read, write, edit files, run commands, and search the web", and the SDK's tool-input-type reference names them explicitly: "Built-in tools include Bash, Read, Write, Edit, Glob, Grep, WebFetch, Agent, and others." WebFetch fetches external content; Agent spawns subagents (see below). In the SDK, the tools option controls which built-ins are actually available to a given agent: tools: ["Read", "Grep"] keeps only the listed built-ins in context (MCP tools are unaffected), while tools: [] strips every built-in so the agent can only call your MCP tools. That's the mechanism behind "scope an agent's tools to its role" when the tools in question are built-ins rather than MCP tools.

Sourcescode.claude.com › overviewcode.claude.com › hookscode.claude.com › custom-toolsfetched 2026-07-30

Agent — the built-in for spawning subagents (formerly named Task)

Practically: "Claude invokes subagents through the Agent tool, so include Agent in allowedTools to auto-approve subagent invocations without a permission prompt." If a coordinator's tool-use log shows Task instead of Agent (or vice versa), that's a version artefact, not a different tool.

Sourcecode.claude.com › subagentsfetched 2026-07-30

Permission-rule syntax scopes what a built-in can actually do

--allowedTools lists tools (using permission-rule syntax) that run without a prompt; to restrict which tools are available at all use --tools instead — allow-listing and availability-restriction are different mechanisms. In --disallowedTools, a bare tool name removes the tool from Claude's context entirely ("Edit" removes Edit outright, "*" removes every tool), while a scoped rule such as Bash(rm *) leaves the tool available but denies only matching calls. Bash rules support prefix matching, and the trailing space matters: Bash(git diff *) allows any command starting with git diff, but without the space, Bash(git diff*) would also wrongly match git diff-index. WebFetch uses its own rule shape — a domain: prefix matched against the hostname: WebFetch(domain:example.com) matches that host; WebFetch(domain:*.example.com) matches any subdomain at any depth but not the apex domain itself.

--allowedTools "Bash(git diff *),Read,Edit"
--disallowedTools "Bash(rm *)"        # Bash stays available; rm is denied
--disallowedTools "Edit"              # Edit removed from context entirely

Sourcescode.claude.com › cli-referencecode.claude.com › headlesscode.claude.com › permissionsfetched 2026-07-30

Built-ins and MCP tools share a permission surface but a different naming convention

Built-in tools are referenced by their bare name (Read, Grep, Bash(...)) in permission rules. MCP tools instead use the namespaced pattern mcp__<server-name>__<tool-name> — for example a list_issues tool on a server named github becomes mcp__github__list_issues. Permission rules can target a whole server (mcp__puppeteer, matching any of its tools), every tool on a server via wildcard (mcp__puppeteer__*), or one specific tool (mcp__puppeteer__puppeteer_navigate). This naming convention is how you tell, in a permission prompt or a tool-use log, whether a given call is a built-in or an MCP-provided tool — directly relevant when deciding (per Task 2.4) whether the agent should prefer a built-in like Grep or a better-described MCP alternative.

Sourcescode.claude.com › permissionscode.claude.com › mcpfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Trace and Refactor a Deprecated Function Using Built-in Tools

Difficulty: Intermediate (2/4)

30 minutes

1. Use Grep to search for all callers of a target function (e.g. processLegacyOrder) across the codebase

Why: Grep searches file contents — it is the correct tool for finding function callers. Using Glob here would fail because Glob matches file paths, not contents. The exam tests this distinction directly and penalises candidates who confuse the two.

You should see: A list of file paths containing calls to processLegacyOrder, with line numbers and matching lines showing the exact call sites. For example: src/OrderProcessor.ts:42: await processLegacyOrder(orderId).

2. Use Glob to find test files matching the caller filenames (e.g. **/*.test.tsx)

Why: Glob matches file paths by naming pattern — it is the correct tool for finding test files by extension or naming convention. This completes the Grep-then-Glob pattern: content search to find callers, then path matching to find their tests.

You should see: A list of test file paths matching the pattern, such as src/OrderProcessor.test.tsx and src/RefundHandler.test.tsx. These correspond to the caller files found by Grep in the previous step.

3. Use Read to examine each caller file and understand the usage pattern and context

Why: Reading files incrementally — only after Grep identifies which files matter — is the correct approach. Reading all source files upfront is a context-budget killer that the exam explicitly penalises. Each Read should be justified by what you discovered in the previous step.

You should see: The full contents of each caller file, showing how processLegacyOrder is called, what parameters are passed, how the return value is used, and whether the function is imported directly or through a wrapper module.

4. Use Edit to replace the deprecated function call with the new API in each caller file

Why: Edit is the preferred modification tool because it targets specific text and uses less context than Read + Write. The exam penalises defaulting to Read + Write for every modification. Always try Edit first — it is faster and more precise.

You should see: Each caller file updated with the new API call replacing the deprecated one. For example, processLegacyOrder(orderId) replaced with processOrder(orderId, { validate: true }). The Edit tool confirms the replacement was made successfully.

5. When Edit fails with a non-unique match, widen old_string with more surrounding lines until it pins down one location (or set replace_all: true if you actually want every occurrence updated). Only fall back to Read + Write if neither option can disambiguate the target

Why: Edit fails when the target text appears multiple times in the file — this is a safety mechanism, not a bug. Per the Edit tool documentation, the documented recovery is to expand the anchor with more surrounding context until it matches one place, or to use replace_all for global replacements. Both keep you on Edit and cost almost nothing in context. Read + Write loads the entire file for what is usually a single-line change — keep it as a last resort.

You should see: On the first try, Edit fails with an error like: old_string matches 3 locations. On the retry with a wider old_string that includes the surrounding function name or unique adjacent line, Edit succeeds and changes exactly one occurrence. If replace_all: true was the right call, every occurrence is updated atomically.

Sources

• Claude Certified Architect Foundations Exam Guide — Domain 2, Task Statement 2.5 — Anthropic
• Claude Code Documentation — Built-in Tools — Anthropic
• Building with Claude API — Anthropic — Anthropic
• Agent SDK overview — Anthropic
• CLI reference — Anthropic
• Permissions — Anthropic
• Headless mode — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Use Grep to search for all callers of a target function (e.g. processLegacyOrder) across the codebase

Why: Grep searches file contents — it is the correct tool for finding function callers. Using Glob here would fail because Glob matches file paths, not contents. The exam tests this distinction directly and penalises candidates who confuse the two.

You should see: A list of file paths containing calls to processLegacyOrder, with line numbers and matching lines showing the exact call sites. For example: src/OrderProcessor.ts:42: await processLegacyOrder(orderId).

Step 2. Use Glob to find test files matching the caller filenames (e.g. **/*.test.tsx)

Why: Glob matches file paths by naming pattern — it is the correct tool for finding test files by extension or naming convention. This completes the Grep-then-Glob pattern: content search to find callers, then path matching to find their tests.

You should see: A list of test file paths matching the pattern, such as src/OrderProcessor.test.tsx and src/RefundHandler.test.tsx. These correspond to the caller files found by Grep in the previous step.

Step 3. Use Read to examine each caller file and understand the usage pattern and context

Why: Reading files incrementally — only after Grep identifies which files matter — is the correct approach. Reading all source files upfront is a context-budget killer that the exam explicitly penalises. Each Read should be justified by what you discovered in the previous step.

You should see: The full contents of each caller file, showing how processLegacyOrder is called, what parameters are passed, how the return value is used, and whether the function is imported directly or through a wrapper module.

Step 4. Use Edit to replace the deprecated function call with the new API in each caller file

Why: Edit is the preferred modification tool because it targets specific text and uses less context than Read + Write. The exam penalises defaulting to Read + Write for every modification. Always try Edit first — it is faster and more precise.

You should see: Each caller file updated with the new API call replacing the deprecated one. For example, processLegacyOrder(orderId) replaced with processOrder(orderId, { validate: true }). The Edit tool confirms the replacement was made successfully.

Use the Edit tool with:
  old_string: "await processLegacyOrder(orderId)"
  new_string: "await processOrder(orderId, { validate: true })"
If the function call appears with different arguments in different places, include surrounding code to make old_string unique.

Step 5. When Edit fails with a non-unique match, widen old_string with more surrounding lines until it pins down one location (or set replace_all: true if you actually want every occurrence updated). Only fall back to Read + Write if neither option can disambiguate the target

Why: Edit fails when the target text appears multiple times in the file — this is a safety mechanism, not a bug. Per the Edit tool documentation, the documented recovery is to expand the anchor with more surrounding context until it matches one place, or to use replace_all for global replacements. Both keep you on Edit and cost almost nothing in context. Read + Write loads the entire file for what is usually a single-line change — keep it as a last resort.

You should see: On the first try, Edit fails with an error like: old_string matches 3 locations. On the retry with a wider old_string that includes the surrounding function name or unique adjacent line, Edit succeeds and changes exactly one occurrence. If replace_all: true was the right call, every occurrence is updated atomically.

// Attempt 1 — fails
// Edit { old_string: "processLegacyOrder(orderId)", new_string: "processOrder(orderId, { validate: true })" }
// Error: old_string matches 3 locations

// Attempt 2 — widen the anchor with surrounding context
// Edit {
//   old_string: "async function handleRefund(orderId: string) {\n  const result = await processLegacyOrder(orderId)",
//   new_string: "async function handleRefund(orderId: string) {\n  const result = await processOrder(orderId, { validate: true })"
// }
// Success — only the handleRefund occurrence changes.

// Or, if you want every occurrence updated atomically:
// Edit { old_string: "processLegacyOrder(orderId)", new_string: "processOrder(orderId, { validate: true })", replace_all: true }

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the work you actually did.