Week 4 — Agents: When LLMs Can Use Tools
Sign in
Week 4 — Agents: When LLMs Can Use Tools
A locked-in brain becomes a worker the moment you give it hands.

Adventure 8

Adventure II — The Story So Far
Where We Left Off
  • Week 1: An LLM is a next-word predictor
  • Week 2: Inside it — tokens, attention, transformers
  • Week 3: You control it with sampling + 5 prompt patterns
  • Week 4 (today): What happens when you give it tools

Adventure 8

What You'll Know in 3 Hours
By the end of today, you can:
1
Explain the limitation
Why a plain LLM can't "do" anything — only describe
2
Read a tool definition
Look at a JSON tool definition and predict how a model will use it
3
Trace the agent loop
Walk through an agent loop step by step
4
Diagnose failures
Identify which of 4 failure modes an agent is in when something goes wrong
5
See through any AI product
Ask "what tools does it have?" — and usually guess right

Adventure 8

The Deal — 3 Ground Rules
1
Prediction before approval
Before clicking "Allow" on any tool call, predict what it'll do
2
Tools fail. Plan for it.
Half this lesson is about what goes wrong
3
Build it on paper before code
Designing agents in your head is the skill

Adventure 8

Before We Start
Quick Calibration
Three questions to warm up your thinking. Don't look anything up — just predict.
Question 1
Can ChatGPT delete a file on your computer? Why or why not?
Question 2
What's the difference between a "chatbot" and an "agent"?
Question 3
If you've used Claude Code or Cursor — what's actually happening when it edits a file for you?

Adventure 8

The Locked-In Brain
Imagine the smartest person you know. Now lock them in a room with no phone, no internet, no books.
Ask them: "What's the weather in Tokyo right now?"
They can't answer. Not because they're not smart — because answering requires looking outside the room.

Adventure 8

That's a Plain LLM
A plain LLM (no tools attached) can't:
  • Read a file on your computer
  • Run code
  • Look up live data
  • Send a message
  • Take any action that affects anything outside its text output
It can only describe things. For three years after ChatGPT launched, that was most people's idea of "AI."

Adventure 8

What Hallucination Looks Like
Ask a plain LLM: "What's today's weather in Tokyo?"
Sometimes — honest
"I don't have access to real-time data."
Sometimes — dangerous
"It's 18°C and partly cloudy in Tokyo today."
Confidently stated. Completely fabricated.
The model has no way to know. So it predicts what a plausible answer would look like — and outputs that.

Adventure 8

📘 Concept Card
Hallucination (in agents)
What: The model generates a plausible-looking but fake value (a date, a fact, an ID) because it doesn't actually have one.
Like: A new employee afraid to admit they don't know your order number — so they confidently make one up.
Why it matters: This is the #1 cause of agent-induced data corruption. Always validate the model's outputs before executing.

✓ Takeaway: Confident output ≠ correct output. The model can't tell you it's guessing unless you teach it to.

Adventure 8

Surprise — Tools Don't Change the Model
What changes when you "give an LLM a tool"?
❌ What does NOT change
  • The model's weights
  • Its training data
  • How it predicts tokens
✅ What DOES change
  • You send a JSON description of the tool along with your prompt
  • You wrap the model in a runtime that watches for tool calls
The model itself is still doing the same thing: predicting next tokens.

Adventure 8

Anatomy of a Tool
{ "name": "get_weather", "description": "Get the current weather in a given city.", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "City name, e.g. 'Tokyo'" } }, "required": ["city"] } }
A name, a description, a parameter schema. The function itself lives in your code, not the model.

Adventure 8

The Tool Call
The model doesn't run anything. It just outputs a structured request:
{ "tool": "get_weather", "args": { "city": "Tokyo" } }
Your code then:
01
Sees this output
Runtime intercepts the structured tool-call JSON
02
Validates and runs
Executes the actual get_weather() function
03
Feeds result back
Returns "18°C, cloudy" into the conversation context
04
Model continues
Resumes reasoning with the new info now in context

Adventure 8

📘 Concept Card
Tool
What: A function description (name + params + docstring) the model can request to be called.
Like: An employee manual entry. "Here's get_weather — call it when needed." The model decides when. Your code decides what happens.
Why it matters: Tools never live in the model. They're plug-in modules around it.

✓ Takeaway: A tool is just a description. The runtime is what makes it real.

Adventure 8

Knowledge Check 1
Predict Before You Flip
The model outputs:
{"tool": "delete_file", "args": {"path": "/etc/passwd"}}
Question 1
What happens next? Predict before discussing.
Question 2
Is the file deleted automatically?
Question 3
Does the runtime have a chance to say no?

Write your answers down before talking to anyone. Your first instinct is data.

Adventure 8

The Agent Loop
messages = [system_prompt, user_question] while True: response = model.generate( messages, tools=available_tools) if response.is_tool_call: result = execute_tool( response.tool_name, response.args) messages.append(response) messages.append(result) continue else: return response.text
That's it. Every "AI agent" is built on this loop.

Adventure 8

Walk Through One Iteration
User asks: "Find the file in Downloads that mentions 'rocket.'"
1
Step 1
Model output: "I'll list the folder first." → emits list_files(directory="Downloads")
2
Step 2
Runtime executes → returns 47 filenames
3
Step 3
Model sees file list → emits read_file(name="essay1.txt"). Checks for "rocket" → not found → tries next file
4
Step 4+
…loop continues until model finds the keyword
5
Final output
"Found it in space_essay.txt"

Adventure 8

Why This Is So Powerful
The model chooses what to do next based on the result of the last step.
Read + decide
Read files, find patterns, decide what to do next
Browse + follow
Browse the web, follow links, summarize what it finds
Run + fix
Run code, see errors, fix them
Anything iterative
Anything you'd hire a careful junior engineer to do
A plain LLM couldn't do any of this. The loop changes everything.

Adventure 8

📘 Concept Card
Agent Loop
What: A while-loop letting a model call tools, see results, and decide next steps.
Like: A human doing research. You check one source, that gives you a lead, you check the next — you can't plan every step upfront.
Why it matters: This loop is the only thing separating a chatbot from a worker. Everything in agent-land is built on it.

✓ Takeaway: Chatbot = one reply. Agent = loop until done.

Adventure 8

Agent vs Chain

Chain
Agent
Steps
Predefined
Decided on the fly
Order
Fixed
Dynamic
Example
Translate → Summarize → Email
"Figure out what user wants and do whatever it takes"
Best for
Repeatable processes
Open-ended tasks
If step fails
Chain breaks
Agent tries something else
Chains are easier to debug. Agents are more flexible. Most real systems mix both.

Adventure 8

Claude Code's Tool List
You're using Claude Code right now. Here's the real tool list (simplified):
Read
Read a file
Write
Write a file
Edit
Find-and-replace inside a file
Glob
Find files matching a pattern (*.py)
Grep
Search file contents for text
Bash
Run a shell command
WebFetch
Fetch a URL
WebSearch
Search the web
Task
Spin off a sub-agent
Each one is just a JSON tool description.

Adventure 8

Watch Claude Code Work
You ask: "Fix the bug in app.py"
1
1. Reads context
Model reads your message + tool list + system prompt
2
2. Inspects first
Decides: need to see the code → Read(file_path="app.py")
3
3. Edits
Sees code + bug → decides what to change → Edit(old_string=..., new_string=...)
4
4. Verifies
Maybe Bash("python app.py") — if error, fix and retry
5
5. Reports
Model decides it's done → responds to you in plain text

Adventure 8

Why Claude Code's System Prompt Is So Long
Tools alone aren't enough. The system prompt teaches the model:
Which tool for which job
Glob for filenames, Grep for content — not interchangeable
How to chain tools
Read before edit. Verify after edit. Never skip steps.
What NOT to do
Don't rm -rf, don't commit without permission
How to handle errors
Read the actual message, don't guess
How to talk to you
Concise, show diffs, ask before destructive actions

Adventure 8

The Agent's Judgment Lives in the System Prompt
A weak system prompt + the same tools = a much worse agent.
"Tools give the agent capability.
The system prompt gives it character."
Tools alone
  • Raw capability, no direction
  • Will use Bash for everything
  • No sense of caution
  • Won't ask before deleting
Tools + strong system prompt
  • Picks the right tool for each job
  • Knows when to pause and verify
  • Has consistent behavior you can trust
  • Asks before anything irreversible

Adventure 8

What Claude Code WON'T Do Without Permission
Even with Bash tool access, Claude Code:
✅ Reads freely
Reads files and searches code without asking
⚠️ Asks before editing
Confirms before writing changes to your files (in approval mode)
⚠️ Asks before shell
Asks before running shell commands that affect your system
❌ Hard limits
Won't rm -rf, force-push, or skip pre-commit hooks unless you explicitly say so

This isn't the model being "smart" — it's the system prompt drawing the lines.

Adventure 8

Knowledge Check 2
Design an Agent
You're building an agent for: "Plan my friend's birthday party."
Question 1
What 3–4 tools does it need? Name them and say what each one does.
Question 2
What should its system prompt say? Write 3–4 key instructions.
Question 3
What could go wrong if you skipped writing a system prompt entirely?

Predict your answers first — then discuss with the person next to you.

Adventure 8

The 4 Ways Agents Fail
Agents are powerful but fragile. Four failure modes show up over and over:
1
Context overflow
Agent "forgets" early instructions
2
Tool errors not handled
Gets stuck or hallucinates on bad results
3
Wrong tool chosen
Solves the problem the long way around
4
Hallucinated arguments
Invents IDs, URLs, or filenames it doesn't have
Knowing the symptoms = much faster debugging.

Adventure 8

Failure 1 — Context Overflow
Every turn adds to the conversation:
  • System prompt + user message + 5 tool calls + 5 results + … it adds up fast
  • Once you exceed the model's context window (e.g. 200k tokens), old messages drop or get summarized
Symptom
Agent "forgets" what you told it 10 minutes ago. Contradicts itself. Asks for info you already gave.
Fix
Summarize old turns before they fall off the window. Use smaller contexts when possible. Keep tool results concise.

Long-running agents are especially vulnerable. Plan for this from the start.

Adventure 8

Failure 2 — Tool Errors Not Handled
Tools fail. File doesn't exist. API returns 500. User cancels.
If the model gets a confusing error and the system prompt doesn't teach it what to do:
Silent corruption
Pretends the error didn't happen and continues — writing bad data
Infinite loop
Retries forever because it never learns to back off
Hallucination
Makes up what the result "should have been" — fabricates data

Fix: Catch errors in the runtime, format them clearly, and teach the model in the system prompt to back off gracefully.

Adventure 8

Failure 3 — Wrong Tool Chosen
The model sees Bash, Read, and WebFetch.
It uses Bash("curl https://...") instead of WebFetch. Both work — but Bash is slower, more expensive, harder to sandbox.
Symptom
  • Agent does things the roundabout way
  • Uses a sledgehammer for a finishing nail
  • Harder to audit what it actually did
Fix
  • Better tool descriptions (say when to use each)
  • System-prompt examples showing the preferred tool
  • Sometimes: remove the redundant tool entirely

Adventure 8

Failure 4 — Hallucinated Arguments
The model emits:
delete_user(id="usr_123")
But usr_123 doesn't exist. It made up the ID.
Symptom
Silent data corruption. "Where did that record come from?" Fake entries appearing. Real data disappearing.
Fix
Require the model to retrieve real IDs from real tools (list_users) before passing them to actions.

Treat model output as untrusted input — validate before executing anything destructive.

Adventure 8

Hands-On A
Read Claude Code's Mind
Open Claude Code. Ask it a non-trivial task (e.g. "rename all foo.py to bar.py in this folder").
Before approving each tool call, pause and predict:
  • What tool will it use next?
  • What arguments?
  • What will the result tell it?

Get to 80% prediction accuracy → you understand the agent loop. Track your score.

Adventure 8

Hands-On B
Spot the Failure Mode
Give Claude Code a deliberately broken task:
  • Ask it to read a file that doesn't exist
  • Ask it to run a command that will fail
  • Give a contradictory instruction
Watch and record:
Does it recover?
Graceful recovery or does it stumble?
Does it loop?
Retries endlessly with the same broken call?
Does it hallucinate?
Makes up a result instead of admitting the error?
Now you've seen each failure mode in real life.

Adventure 8

Hands-On C
Design an Agent on Paper
Pick a task you do manually. Example: "Post a tweet about today's weather, but only if it's interesting (rain, snow, very hot/cold)."
Design — no code:
01
List the tools
What does it need? (get_weather, post_tweet, get_current_city?)
02
Write the system prompt
How does it decide what counts as "interesting"?
03
Write the kickoff prompt
What does the user send to start the agent?
04
Map the failure modes
What could go wrong? How does each one get handled?

If you can spec it on paper, you understand agents better than 95% of people who use them.

Adventure 8

Live Exercise
Watch Claude Code Do a Real Task
Pick something with at least 3 expected tool calls. Run it. Pause at each step.
For each tool call, the class predicts the next call before clicking Allow.
Round 1
Teacher runs the task. Class predicts together.
Round 2
A student runs their own task. Rest of class predicts.
Debrief
Where were the surprises? Which failure mode almost happened?
This is the single best exercise for building agent intuition.

Adventure 8

Discussion — Your Favorite AI App
What tools does it have?
ChatGPT + Code Interpreter
What tools? Think about what it can actually do vs. just describe.
Cursor
What tools? How does it differ from Claude Code's list?
Notion AI
What tools? What are the limits of what it can touch?
Perplexity
What tools? What's the core loop that makes it work?

Once you see "every AI product is just a system prompt + tools + loop," the whole landscape clarifies.

Adventure 8

The 3-Hour Summary
You now understand:
✅ The locked brain
A plain LLM is locked in its head — can describe but can't do
✅ Tools are just JSON
Not magic — the runtime around the model executes them
✅ The agent loop is 8 lines
A while-loop letting the model call tools and decide next steps
✅ Claude Code is exactly this
Visible tools + a system prompt with judgment
✅ 4 failure modes
Context overflow, unhandled errors, wrong tool, hallucinated args — you can spot each one

Adventure 8

Glossary
Tool
Function description (name + params + docs) the model can request to be called
Tool call
Structured output where model says "please run tool X with args Y"
Agent loop
While-loop letting the model call tools and decide next steps
Agent
LLM + tools + the loop tying them together
Chain
Predefined sequence of LLM/tool steps; less flexible than an agent
Context window
Max number of tokens (system + history + new) the model can see at once
Hallucination
Model invents a value (ID, URL, filename) instead of admitting it doesn't have one

Adventure 8

This Week's Mission + Week 5 Preview
This week
  • Read Claude Code's mind on 3 real tasks — note where you predicted wrong. Those are your learning moments.
  • Design one agent on paper. Be ready to share it next week.
Next week — Frameworks & MCP
Every AI company has built the same agent loop from scratch. Same "read file" tool, same "search web" tool, all slightly different.
Anthropic published a standard called MCP — Model Context Protocol. One protocol, every agent uses every tool. Like USB for AI.
We'll learn the 4 major frameworks AND plug a new MCP server into Claude Code together.

Adventure 8