Claude Architect WorkshopPDFEPUBlearnwithparam.comkaas.team

Foundations, lesson 13

Built-in search tools

Search with Grep and Glob, not with a shell

A new developer at Lumen Supply asks where the tax amount is rounded. The agent has a shell, so it runs command after command and reads far more files than the answer needs. The answer sits in one of them. This is the agent at Lumen Supply, an online electronics shop. You will watch a shell search, then give the agent search tools and a brief that says to read only what matches.

I doWatch the failure and its fix.

Built-in tools find files and text

Claude Code and the Agent SDK ship tools for exploring a repository. Grep finds lines by content. Glob finds files by name. Read and Write handle a whole file, and Edit replaces text that appears once, unless it is told to replace every copy with its replace_all option.

The model picks the tool. The harness runs it and returns the result. A shell returns whatever a command prints, so the agent can pull far more into its context than the question needs.

On macOS and Linux, a current Claude Code session searches through its shell unless Glob and Grep are named in the tool list. The fix in this lesson names them, and that is what puts them in the agent's hands.

Search first, then read only what matches.Questionone functionGlob and Grepfind by name and by contentReadthe one matchAnswernames the filethe tools and the brief are written in explore.pySearch first, then read only what matches.Questionone functionGlob and Grepfind by name and by contentReadthe one matchAnswernames the filethe tools and the brief are written in explore.py

Search tools answer with a small read

The agent runs two searches (Grep, then Glob), then reads one file, and names it in the answer. Open the agent card to see the calls in order. The repository card shows one file opened and how many characters were read.

  1. ColleagueWhich function rounds a tax amount, and in which file?
    Show the result
    Which function rounds a tax amount, and in which file?
  2. Agent3 tool calls: Grep, Glob, Read
    Show the result
    Grep
Glob
Read
  3. Repository1 file opened, 1024 characters read
    Show the result
    [
  "src/tax/service.py"
]
  4. AgentThe function is round_tax(amount), defined in src/tax/service.py at line 46. It returns round(amount, 2), so it…
    Show the result
    The function is round_tax(amount), defined in src/tax/service.py at line 46. It returns round(amount, 2), so it rounds the tax amount to two decimal places. I searched with Grep for "round" names and then read only that file; the Glob for /*tax* returned nothing, so the Grep match was the only lead.

1 file opened: found by search, small read.

The tools and the brief as written

tools lists the built-in tools the agent may use. brief is the prompt for one question. The starting version allows only a shell and asks the agent to read every file.

Reading costs context, the text the model can see at once. Every character read is paid for again on each later turn. The recorded runs below show the gap: a shell search reads about five times as many characters as a search tool.

starter/explore.py
1"""How the agent explores a repository: its tools and its brief."""234def tools() -> list[str]:5 """The built-in tools the agent may use.6 TODO(workshop): search with Grep and Glob, and read with Read.7 """8 return ["Bash"]91011def brief(question: str) -> str:12 """The prompt the agent gets for one question.13 TODO(workshop): tell it to search first and read only what matches.14 """15 return f"{question}\n\nRead every file in the repository, then answer."

What does a shell search read?

The agent holds a shell and is asked where the tax is rounded. The repository has many modules, and the answer sits in one.

Predict: What does the agent read?

  1. ASeveral files, since a shell search does not know which one is the answer.
  2. BThe one file that matches.
Show the answer

A. A shell search has no idea which file is the answer, so the agent reads until it finds out.

The shell reads too much

This is the same question with the starting code. The agent makes three Bash calls. One lists every file and one greps every file, for an answer that sits in one.

It names the right file, so the result card is green. The cost shows in the characters read. The coupon question is worse: the shell prints every file in the repository.

This is a real Claude Haiku 5.5 run, recorded once and replayed here.

  1. ColleagueWhich function rounds a tax amount, and in which file?
    Show the result
    Which function rounds a tax amount, and in which file?
  2. Agent3 tool calls: Bash
    Show the result
    Bash
Bash
Bash
  3. Repository1 file opened, 5193 characters read
    Show the result
    [
  "src/tax/service.py"
]
  4. AgentThe function is round_tax in src/tax/service.py. It returns round(amount, 2), rounding the tax amount to two…
    Show the result
    The function is round_tax in src/tax/service.py. It returns round(amount, 2), rounding the tax amount to two decimal places. I didn't print every file in full. I read the tax service file directly and searched all of the repository's files for rounding-related terms (round, quantize, ceil, floor, Decimal, trunc), and this was the only match.

1 file opened: found by search, small read.

Offer search tools and say to search first

The fix takes away the shell and lists Glob, Grep and Read. An agent that only explores needs no tool that changes a file. The brief says to search first, read the one file that matches, and name the file in the answer.

A question like this one never edits, but the tools you list for a task that does matter. Edit needs text that appears once.

A longer piece of the surrounding text can make it unique, and replace_all changes every copy. When a file holds the same line six times and only two should change, neither helps. The agent reads the whole file and writes it back with the change.

How the agent finds one function.ColleagueAgentRepositoryquestionsearch and readmatchesanswer
explore.pygreen lines are what the fix adds
1"""How the agent explores a repository: its tools and its brief."""234def tools() -> list[str]:5 """The built-in tools the agent may use: search, then read."""6 return ["Glob", "Grep", "Read"]789def brief(question: str) -> str:10 """The prompt the agent gets for one question."""11 return (12 f"{question}\n\n"13 "Search first: Glob finds files by name and Grep finds text by "14 "content. Then Read the one file that matches, and no others. "15 "Do not edit anything. Name the file in your answer."16 )

Long investigations: subagent, scratchpad, compact

A real investigation runs for hours, so the context fills and answers drift toward generic ones. The run below is the coupon question with search tools: two searches and one file opened, where the shell printed every file. Three habits keep a long session small.

  • An Explore subagent does the noisy discovery in its own context and returns a short answer.
  • A scratchpad file keeps the findings outside the window, so a reset does not lose them.
  • /compact replaces a long history with a summary. The session goes on.

Write a short summary before the next phase. A run that stops partway needs state saved on disk, such as a manifest of finished steps, because a new session starts empty.

Resume a named investigation when its files are unchanged. Fork it to try two approaches from one point. Start fresh with a summary when files changed, since old results are stale. Use plan mode, which never edits, for open designs, and edit directly when one file and one answer are clear.

  1. ColleagueHow many coupons can one order use, and where is that set?
    Show the result
    How many coupons can one order use, and where is that set?
  2. Agent3 tool calls: Grep, Read
    Show the result
    Grep
Grep
Read
  3. Repository1 file opened, 1081 characters read
    Show the result
    [
  "src/coupons/models.py"
]
  4. AgentOne order can use up to 3 coupons. The limit is the constant MAX_COUPONS_PER_ORDER = 3, defined at line 46 of…
    Show the result
    One order can use up to 3 coupons. The limit is the constant MAX_COUPONS_PER_ORDER = 3, defined at line 46 of src/coupons/models.py. I found it with a Grep for coupon-related max/limit terms, then read only that file. I did not check whether service.py or api.py enforce the limit.

1 file opened: found by search, small read.

We doChange one setting at a time and predict.

The same question, two ways to look

Use the switch to ask the question with the shell, then with the search tools. The card marked "This is where the runs split" shows how many files each one opened.

This part is interactive in the lab: run ./workshop watch builtin-tools-explore.

Try it: tools and questions

Change one setting at a time. Pick a question, then switch between the shell and the search tools. The shell works. It only costs more.

Every combination is a recorded run, so this works with no internet.

This part is interactive in the lab: run ./workshop watch builtin-tools-explore.

Exploring in the Agent SDK

The same question, with the Agent tool added beside the search tools. The brief tells the main agent to hand the search to an explorer subagent that holds Grep, Glob and Read in its own context. A subagent can only use tools its parent holds, so the main agent lists them too.

The harness passes each tool list to the SDK, which runs the agent in a fresh copy of the repository.

This is a real Claude Haiku 5.5 run through the Agent SDK.

app/sdk_agent.py
1"""The delegated run: the main agent holds one tool and spawns a searcher.23The main agent's tool list is `SPAWN` beside the search tools, since a4subagent can only use tools its parent holds. The explorer subagent gets5its own context and only the tools its definition names.6"""78from claude_agent_sdk import AgentDefinition910SPAWN = "Agent"11HAND_OFF = (12 "\n\nHand the search to the explorer subagent "13 "(subagent_type explorer), wait for its reply, and name the file."14)151617def explorer() -> dict[str, AgentDefinition]:18 """The one subagent a delegated run may spawn: search, read, report."""19 return {20 "explorer": AgentDefinition(21 description="Finds where something is set in the repository.",22 prompt="Search with Grep and Glob, Read only the file that "23 "matches, and reply with the file and the line in two sentences.",24 tools=["Grep", "Glob", "Read"],25 model="haiku",26 )27 }
  1. ColleagueWhich function rounds a tax amount, and in which file?
    Show the result
    Which function rounds a tax amount, and in which file?
  2. Agent7 tool calls: Agent, Glob, Grep, Read, SubagentHandback
    Show the result
    Agent
Glob
Glob
Grep
Read
SubagentHandback
Read
  3. Repository1 file opened, 1574 characters read
    Show the result
    [
  "src/tax/service.py"
]
  4. AgentThe function is round_tax(amount), defined in src/tax/service.py at line 46. It returns round(amount, 2), so it…
    Show the result
    The function is round_tax(amount), defined in src/tax/service.py at line 46. It returns round(amount, 2), so it rounds to two decimal places. The explorer subagent found it, and I confirmed it by reading that file. The rest of the file is a series of trivial service_tax_N functions that don't do any rounding.

1 file opened: found by search, small read.

You doFix the starting code, then test yourself.

You do: search before you read

Copy the starting code and open work/builtin-tools-explore/explore.py. tools() offers only Bash, and brief() tells the agent to read every file.

Terminal
./workshop start builtin-tools-explore
./workshop check builtin-tools-explore
./workshop watch builtin-tools-explore

The checks want Grep and Glob in place of the shell. The brief must keep the question, say to search before reading, and ask for the file name in the answer.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

1. A teammate must find every caller of applyDiscount across 60 source files. Which built-in tool answers it in one call?

  1. AGlob with the pattern **/*applyDiscount*.
  2. BGrep for applyDiscount across the source directory.
  3. CRead every file under src and scan the text.
  4. DRun ls -R in a shell and look for the name.
Show the answer

Answer: B

  • A Glob matches file names. A caller sits inside a file, so no name holds it.
  • B Correct. Grep searches file contents, so each caller comes back with its file and line.
  • C Sixty reads put the whole repository in the context to find a few lines.
  • D A listing shows file names only, never the lines inside them.

2. An agent must list the 40 files whose names end in .test.ts. Which call does it in one step?

  1. AGlob with the pattern **/*.test.ts.
  2. BGrep for .test.ts across the repository.
  3. CRead each directory and note the test files by eye.
  4. DGrep for the word describe and keep the matching files.
Show the answer

Answer: A

  • A Correct. Glob matches file names and returns the paths without opening any file.
  • B Grep looks inside files. It would only find files that mention that text.
  • C That reads far more than the 40 paths needed, one directory at a time.
  • D A file can hold describe and not be a test file. The name is the signal here.

3. Edit refuses to change TIMEOUT = 30 because that text appears 6 times in one file. Only 2 of the 6 lines should change, and no nearby text tells them apart. What gets the change made?

  1. ARetry the same Edit call, since a later try picks the first match.
  2. BTurn on replace_all, so Edit changes all 6 copies.
  3. CUse Glob to narrow the file list until the match is unique.
  4. DRead the file, then Write the whole file back with the 2 lines changed.
Show the answer

Answer: D

  • A Edit needs text that appears once. Repeating the call gives the same refusal.
  • B replace_all would change all 6 lines, and 4 of them must stay as they are.
  • C Glob works on file names. The 6 matches are inside one file.
  • D Correct. Read and Write handle whole files, so they do not need unique text.

4. Which two statements about Read, Write and Edit are true? Select two.

  1. ARead and Write handle a whole file at a time.
  2. BBy default, Edit changes every matching line in one call, however many match.
  3. CEdit replaces a piece of text that appears once in the file.
  4. DWrite patches only the lines it is given and keeps the rest.
Show the answer

Answer: A, C

  • A Correct. Read returns the file and Write replaces it.
  • B Edit needs text that appears once unless replace_all is set. By default a repeated string is refused.
  • C Correct. The text must be unique so the tool knows which spot to change.
  • D Write replaces the whole file with what it is given.

5. A 3-hour investigation starts giving generic answers. The first findings are about 90,000 tokens back. What fixes the drift?

  1. AAsk for shorter answers from here on.
  2. BStart a new session and repeat the work from the top.
  3. CWrite each finding to a scratchpad file and re-read it when answers drift.
  4. DAdd a line to the prompt that says to stay specific.
Show the answer

Answer: C

  • A Short answers do not bring the early findings back in reach.
  • B That throws away 3 hours of findings and pays for them again.
  • C Correct. The file keeps the findings outside the window, so they stay within reach.
  • D A prompt cannot return text that has left the window.

6. Noisy discovery pours 60,000 tokens of search output into the main context before any real work starts. What keeps it out?

  1. AHand the discovery to a subagent that returns a short answer.
  2. BAsk the agent to print less of each result.
  3. CSwitch the main agent to a larger model.
  4. DClear the context after discovery and ask the question again.
Show the answer

Answer: A

  • A Correct. The subagent holds the noise in its own context and returns a few lines.
  • B Tool results enter the context whatever the agent prints.
  • C A larger model still carries the same 60,000 tokens.
  • D A clear drops the findings along with the noise.

7. A long run stops partway through its steps. Which thing lets a fresh session continue from the next one?

  1. AThe old chat transcript, which reloads itself in the new session.
  2. BThe model's memory of the run.
  3. CA longer timeout on the next run.
  4. DA saved manifest of the 40 finished steps.
Show the answer

Answer: D

  • A A new session starts empty unless something is loaded into it.
  • B The model keeps nothing between sessions.
  • C A timeout limits a run. It stores no progress.
  • D Correct. Structured state on disk tells the new session where to start.

8. A long task is about to start its next phase. Which two steps carry the work across? Select two.

  1. ARun /compact to delete the session and begin with nothing.
  2. BWrite the findings so far as a short summary.
  3. CPaste in every file that was read, so nothing is lost.
  4. DRun /compact so the session shrinks and keeps a summary.
Show the answer

Answer: B, D

  • A Compaction replaces the history with a summary. The session goes on.
  • B Correct. A summary gives the next phase its starting facts in a few lines.
  • C Pasting 40 files refills the window the phase needs free.
  • D Correct. Compaction trades the long history for a summary and frees the window.

9. Yesterday's 2-hour investigation of a flaky test is saved as checkout-flake, and no file has changed since. What is the best start today?

  1. AStart fresh and paste a summary.
  2. BResume the named session.
  3. CFork the session so the original is kept.
  4. DCompact the old session and delete it.
Show the answer

Answer: B

  • A That rebuilds context that is still current and loses the detail.
  • B Correct. The context is current, so resuming keeps every finding.
  • C A fork is for trying a second path. It is not needed to continue one.
  • D Compaction shrinks a session and deleting it would lose the work.

10. Two fixes could work, and you want to try each from the same point without either disturbing the other. What do you do?

  1. AResume the session and try them one after the other.
  2. BStart two new sessions and read the code again in each.
  3. CFork the session at that point, one fork per fix.
  4. DResume the same session in two terminals at once.
Show the answer

Answer: C

  • A The second try would start from the first one's changes.
  • B That repeats the reading twice and loses the shared context.
  • C Correct. Each fork starts from the same history and then goes its own way.
  • D Both terminals would write into one history and mix the two tries.

11. Two files read yesterday changed overnight after a pull of 14 commits, so old tool results are stale. What is the best start?

  1. AStart a new session that opens with a summary of the findings.
  2. BResume the old session and carry on.
  3. CFork the old session and keep going in the fork.
  4. DRun /compact and continue in the same session.
Show the answer

Answer: A

  • A Correct. The summary keeps the conclusions and drops the stale file contents.
  • B Resume would trust tool results that no longer match the files.
  • C A fork copies the same stale results.
  • D Compaction summarizes old results. It does not re-read the changed files.

12. Which two things make resuming a session go well? Select two.

  1. AA session name or id to find it again.
  2. BA fresh summary, since resume discards the old history.
  3. CNo check of the repo, since resume reads changed files on its own.
  4. DA note of which files changed since the session ended.
Show the answer

Answer: A, D

  • A Correct. Without a name there is no session to resume.
  • B Resume keeps the history. A summary is for starting fresh.
  • C Resume does not refresh old tool results, so changed files go unnoticed.
  • D Correct. The note tells the agent which old results to distrust.

13. A caching change has three valid designs with different costs, and the team has not picked one. How should the work start?

  1. AEdit directly and benchmark afterward.
  2. BPick the cheapest design and let the tests decide.
  3. CAsk for the change one file at a time.
  4. DStart in plan mode and weigh the three designs first.
Show the answer

Answer: D

  • A Edits would lock in one design before anyone compared the three.
  • B Tests check behavior, not which design is better.
  • C Small steps do not settle which design to follow.
  • D Correct. Plan mode explores and proposes, so a person chooses before any edit.

14. A stack trace names one line in one file, and the fix is clear. A plan would take 40 minutes. How should you work?

  1. APlan it in plan mode so a person approves the edit.
  2. BSend an Explore subagent to map the repository first.
  3. CEdit it directly, since one file with one answer needs no plan.
  4. DHave Claude interview you about the design.
Show the answer

Answer: C

  • A A plan adds 40 minutes to a fix with one answer.
  • B The trace already names the file, so there is nothing to discover.
  • C Correct. A small, clear fix is faster to do than to plan.
  • D An interview is for open questions. This one has none.

15. A migration touches many modules, and finding them means reading dozens of files. What keeps that discovery out of the main context?

  1. APlan mode on its own, since it reads without editing.
  2. BAn Explore subagent that searches and returns a short list.
  3. CDirect edits, so nothing needs to be read first.
  4. DA longer system prompt with the module names.
Show the answer

Answer: B

  • A Plan mode still reads those 45 files into the main context.
  • B Correct. The reading stays in the subagent and only the list comes back.
  • C Editing the modules unread is how the wrong edits happen.
  • D A prompt cannot list what nobody has searched for yet.

16. Which two rules help you pick between plan mode and a direct edit? Select two.

  1. AUse plan mode so Claude writes the plan into the source files.
  2. BPlan when the design is open or many files change.
  3. CEdit directly when one file and one answer are clear.
  4. DPlan every change so nothing surprises the team.
Show the answer

Answer: B, C

  • A Plan mode blocks edits. The plan is a proposal, not a change.
  • B Correct. A plan lets a person choose before a wide change lands.
  • C Correct. Planning a clear fix costs more than the fix.
  • D Planning a one-line fix wastes the time the plan was meant to save.

Play: predict the output

This version offers the search tools but keeps the old brief.

python
def tools() -> list[str]:
    return ["Grep", "Glob", "Read"]


def brief(question: str) -> str:
    return f"{question}\n\nRead every file under src, then answer."

Predict: Asked where the refund limit is set, how much does the agent read?

  1. AEvery file under src, because the brief asks for that even with Grep offered.
  2. BOnly the file Grep matches, because the search tools are cheaper.
Show the answer

A. The tool list says what the agent may do, and the brief says what it should do. Tell it to search first and read only the files that match.

References

Conclusions

  • Grep finds lines by content, Glob finds files by name, and Read opens the one file that matched.
  • Fewer, narrower tools keep the read small, and a brief that says to search first keeps the agent on the path.
  • An Explore subagent keeps noisy discovery out of the main context, and a scratchpad keeps findings across a reset.

You can now choose built-in tools and write a brief that keeps an agent's reading small.

Grep

A tool that finds lines by content

Glob

A tool that finds files by name pattern

Explore subagent

A helper that searches in its own context and returns a short answer

Scratchpad

A notes file that holds findings outside the context window