2.5 Built-in tools: Read, Write, Edit, Bash, Grep, Glob
| Tool | Job | Choose it for |
|---|---|---|
Grep | Search file contents for a pattern | Function names, error message strings, import statements, "all callers of X" |
Glob | Match file paths by pattern | **/*.test.tsx, "all YAML under config/" |
Read | Load a full file | Understanding a file, or as the first half of the Edit fallback |
Write | Write a full file | New files; rewriting a file whose contents you already loaded |
Edit | Targeted modification via unique text matching | Surgical changes that keep the rest of the file untouched |
Bash | Shell execution | Builds, tests, git, anything without a dedicated tool |
The Edit fallback
Edit requires the anchor text to be unique. When it fails on a non-unique match, the reliable fallback is Read the file, then Write it back with the modification. (Adding surrounding lines to make the anchor unique is the other move, but Read + Write is the answer the objectives name.)
Incremental codebase understanding
Start with Grep to find entry points, then Read to follow imports and trace flows. Do not read all files upfront — it exhausts the context window before the interesting question is reached.
To trace usage of a function across wrapper modules: first identify all exported names, then Grep for each name across the codebase. A single search for the original name misses everything that goes through a re-export.
Quiz
- Question 1
A developer asks the agent to find every caller of normalizeInvoice in a 4,000-file TypeScript repository. The agent opens src/index.ts, follows its imports, and twelve minutes later has Read 60 files and found three callers. What should it have done?
- Question 2
An Edit call fails because the anchor text "return result;" occurs eleven times in the target file, and the change applies to exactly one of them. The file is generated, so the eleven occurrences close eleven identically shaped functions and no neighbouring line is unique either. What is the appropriate next move?
- Question 3
A developer asks the agent to list every Storybook story file in the repository. Stories are named *.stories.tsx and live beside the components they document, scattered across 30 directories. Which approach is correct?
- Question 4
Asked to explain how a 300-file service handles authentication, the agent Reads all 300 files before answering. The answer is correct, arrives 25 minutes later, and leaves the session context nearly exhausted. What approach should it have taken?