Module 4: The Agent's Toolbox — How They Interact with Your Code

Module 4: The Agent's Toolbox — How They Interact with Your Code

Next →

Description

Module 03 explained what an agent is: LLM + tools + agentic loop + autonomy. This module goes deeper into the second component — tools — and explains exactly which tools a coding agent has, how it uses them, and how it "sees" your codebase.

An agent without tools is just a chatbot. The tools are what transform a language model into something that can read your files, run your tests, search your code, and modify your project. But the tools are also what make an agent potentially dangerous: if it can write files and run commands, it can break things.

By the end of the 5 capsules, you'll be able to name the tools of each category, trace how the agent decides which one to use in a real task, configure files like CLAUDE.md or .cursorrules for your own project, and calibrate permissions knowing exactly what risk you accept with each level.

Where We Are in the Guide

Module 01: The paradigm shift                ✅ Completed
Module 02: How LLMs work                      ✅ Completed
Module 03: From chatbots to coding agents     ✅ Completed
Module 04: The agent's toolbox                ← YOU ARE HERE
Module 05: The developer as director
Module 06: The fundamental workflow
Module 07: Project: Build a mini-agent

This is Module 04 of 7. Modules 02 and 03 gave you the theory (how the LLM works, how it becomes an agent). This module is the most concrete one so far: which tools it has, how it uses them, and how you configure its access to your project.

The Three Questions of This Module

1. WHAT CAN a coding agent DO?
   → The three categories of tools: file, shell, web
   → What's inside each category
   → Concrete examples

2. HOW does it "SEE" YOUR CODEBASE?
   → It doesn't read everything at once
   → Exploration strategies (context gathering)
   → The detective analogy

3. HOW DO YOU CONTROL its ACCESS?
   → Context management for large projects
   → Configuration files (CLAUDE.md, .cursorrules, AGENTS.md)
   → Permissions and sandboxing

The Analogy of the New Technician in Your House

IMAGINE: you hire a technician to fix something in your house.

The technician (the agent) has SKILLS (tools):
→ They know how to read blueprints
→ They know how to use power tools
→ They know how to call a supplier to order a part

But the technician just arrived. They need:

1. A MAP OF YOUR HOUSE (context gathering)
   → They don't know your kitchen, bathroom, where the keys are
   → They have to explore and ask before acting

2. CLEAR RULES (configuration + permissions)
   → "You can enter the kitchen, not the baby's room"
   → "You can move the furniture, but ask me before throwing anything away"
   → Without rules, they can decide wrong — even with good intentions

3. A BRIEF (CLAUDE.md / AGENTS.md / .cursorrules)
   → "This house was designed by X, the wires are in Y"
   → "If you see Z, it's not an error, it's how we do it"
   → Without the brief, they repeat obvious questions

The three questions of the module map to those three elements:

ElementTool/CapabilityCapsule
The technician's skillsTools (file/shell/web)02
The map of the houseContext gathering03
A strategy for large housesContext management04
Brief + rulesCLAUDE.md, permissions05

From Theory to Concrete

MODULE 03 (theory):
"The agent has tools that let it interact
 with the codebase"

MODULE 04 (concrete):
"The agent has file_read, file_write, search, grep,
 shell_execute, web_search, and this is how it decides
 which to use, this is how it sees your project, and this is
 how you configure what it can and cannot do"

A Real Task: Tracing the Tool Calls

To anchor this module, consider a concrete task:

"Refactor the /search endpoint so that it uses the new cache layer instead of calling the database on every request."

Look at what a coding agent does step by step — and which capsule of the module each step corresponds to:

STEP 1 → glob "**/search*.py"                    [Capsule 02: file ops]
         "Find files related to search"
         Result: search_handler.py, search_service.py, test_search.py

STEP 2 → grep "cache" in the codebase            [Capsule 02: file ops]
         "Find the new cache layer"
         Result: finds cache_layer.py + 12 references

STEP 3 → file_read cache_layer.py                [Capsule 02: file ops]
         file_read search_handler.py             [Capsule 03: context gathering]
         "I build a mental model before changing"

STEP 4 → file_read CLAUDE.md (if it exists)      [Capsule 05: configuration]
         "Are there project conventions?"
         Finds: "Use cache_layer.get_or_set() for reads"

STEP 5 → file_edit search_handler.py             [Capsule 02: file ops]
         "I apply the refactor"

STEP 6 → shell_execute "pytest test_search.py"   [Capsule 02: shell]
         "I verify I didn't break anything"

STEP 7 → shell_execute "git diff"                [Capsule 02: shell]
         "I review my own change before reporting"

Seven steps. Five different tools. Two categories (file + shell). One configuration file read. Each one is developed in a capsule of the module.

What the agent did NOT do:

  • ❌ Read all the project's files (limited by the context window — Capsule 04)
  • ❌ Modify files without having read them first (the detective strategy — Capsule 03)
  • ❌ Run dangerous commands without confirmation (permissions — Capsule 05)

This module teaches you to predict and direct that flow.

Prerequisites

Required knowledge:

  • ✅ Module 03 completed (agentic loop and tool calling understood)
  • ✅ A code project of your own for the exercises

Recommended:

  • ✅ Access to a coding agent (Claude Code, Cursor, Copilot)
  • ✅ Familiarity with the terminal (basic commands)

Module Roadmap

Capsule 01 — Module introduction (this capsule)

The three questions of the module. From theory to concrete. The 7-tool-calls scenario.

Capsule 02 — File operations, shell, and web search

The three categories of tools with real examples. File read/write/search, shell execute, web search. How the agent decides which one to use and what arguments to pass it.

Capsule 03 — How agents "see" your codebase

Context gathering strategies. The detective analogy. The agent as explorer: it doesn't see everything at once, it investigates step by step. Top-down and feature-tracing patterns.

Capsule 04 — Context management

What fits in the context window and what doesn't. Strategies for large projects. How to optimize context window usage with your prompts. Compaction and selective reading.

Capsule 05 — Configuration and permissions

CLAUDE.md, AGENTS.md, .cursorrules: what they are and what they're for. Permission systems. Sandboxing. Why boundaries matter.

Progression map

Capsule 01 (this)     → Context and motivation
Capsule 02            → What tools exist (the toolbox)
Capsule 03            → How the agent explores your code
Capsule 04            → Context limits and how to handle them
Capsule 05            → Configuration and access control

Difficulty: ⭐⭐ ────────────────────────▶ ⭐⭐⭐

What You'll Achieve in This Module

By completing the 5 capsules:

  1. Name and describe each tool a coding agent uses (file_read, file_write, grep, shell_execute, web_search, etc.)
  2. Trace the agent's sequence of tool calls in a real task
  3. Optimize your prompts to reduce context window consumption
  4. Configure files like CLAUDE.md or .cursorrules for your project
  5. Calibrate permissions knowing what risk you accept at each level

The before and after

BEFORE the module:
→ "The agent reads my code and modifies it" (vague)
→ "I don't know how it decides which files to read"
→ "I don't know what CLAUDE.md or .cursorrules are"
→ "I don't know what permissions the agent has"

AFTER the module:
→ I know the three categories of tools in detail
→ I understand the agent's context gathering strategy
→ I know how to configure my project's static context
→ I understand the permission system and can configure it

Connection with the Final Project

In Module 07, you'll implement tools for your mini-agent:

TOOLS YOU'LL IMPLEMENT:
→ read_file: read the project's files
→ write_file: create/modify files
→ list_directory: see the folder structure
→ run_command: run commands in the terminal

TO IMPLEMENT THEM YOU NEED TO UNDERSTAND:
→ What each tool does (this module, Capsule 02)
→ How the LLM decides which one to use (Module 03 + this capsule)
→ What parameters it receives and what it returns (Capsule 02)
→ What security restrictions to apply (Capsule 05)

Traps to Avoid While Taking This Module

Five predictable misunderstandings. Anticipate them before starting.

1. "Reading a file is free"

No. Every file_read consumes tokens from the context window (sometimes thousands, depending on the file). If the agent reads 20 files in a session, there may be few tokens left to reason and generate the answer. This is the direct connection with Module 02 (context windows). Capsule 04 explains the consequences and how to budget.

2. "CLAUDE.md or AGENTS.md are optional"

In small projects, yes. In real projects, no. Without a configuration file, the agent repeats obvious questions, misinterprets conventions, and produces code that violates your team's standards. The difference between an agent "that understands my project" and one "that seems foreign" is typically this file. Capsule 05 teaches you to write a good one.

3. "Permissions are a nuisance that slows the agent down"

Permissions are your protection, not an obstacle. An agent with unrestricted shell_execute can delete files, make unwanted commits, or alter system configuration. Capsule 05 helps you calibrate the balance between speed and security — it's not a binary trade-off.

4. "More tools = better agent"

No. More tools means more options for the model to choose which to use — and that increases the probability of selection errors. The most effective agents usually have a curated toolbox, not an exhaustive one. Capsule 02 explains the principle.

5. "When the agent calls shell_execute, it runs directly on my system"

No. The agent requests to execute — the harness (the system that orchestrates the agent) decides whether to allow it. That decision is mediated by your permissions and your confirmation. Capsule 05 develops this protocol. It's the same distinction from Module 03 (tool calling), applied to the specific toolbox.

Diagnosis: What's Your Starting Point?

Five questions to calibrate before starting.

Question 1: Can you name at least 5 tools your favorite coding agent can use?

If yes: Do you know what arguments each one receives? Capsule 02 formalizes this with examples.

If no: It's exactly what Capsule 02 gives you. Leaving the module without being able to name them is a sign that a second pass is needed.

Question 2: When the agent works in your codebase, does it read all the files? If not, how does it decide which ones?

If you said "it reads all of them": you're missing an understanding of context gathering. Capsule 03 corrects the model for you: the agent acts like a detective, not a reader.

If you said "it doesn't read them all, it searches with grep": you're on the right track. Capsule 03 gives you the specific patterns (top-down, feature-tracing, hub-spoke).

Question 3: Have you written or read a CLAUDE.md, AGENTS.md, or .cursorrules file? Do you know what goes inside?

If never: Capsule 05 teaches you what to include and what not to. It's one of the module's most practical outputs.

If yes: is yours alive or did it stay as a TODO from day 1? Capsule 05 gives you a rubric to audit it.

Question 4: Do you know what happens when the context window fills up in the middle of a session?

If you said "everything gets deleted": partially. Modern agents have strategies (compaction, summarization). Capsule 04 explains them.

If you said "I don't know": it's the most common case. Capsule 04 is the answer.

Question 5: Do you blindly trust that your coding agent won't execute something destructive?

If yes: Capsule 05 gives you tools to distrust productively — not out of paranoia, but by design.

If no: do you know exactly what permissions your agent has right now? Capsule 05 helps you audit and configure it.

If you hesitated on 3 or more: this module fills critical gaps for you. If you answered them all with confidence, use it as a review focused on Capsule 04 (context management), which tends to be the most underdeveloped one.

How to Work Through This Module

  1. Capsule 02 is the most practical. It describes the tools with real examples — read it with your agent open next to you.
  2. Capsule 03 is the most revealing. It changes how you think about how the agent "sees" your code.
  3. Capsule 04 connects with Module 02. Context window applied: you'll learn to budget.
  4. Capsule 05 is the most configurable. What you learn applies immediately to your projects.

Estimated time:

Capsule 01 (this)  →  5 min
Capsule 02         → 12 min
Capsule 03         → 10 min
Capsule 04         → 10 min
Capsule 05         → 12 min + configuration

Total: ~50-60 minutes

Evidence of Success

Before moving on to Module 05 (The developer as director), you should be able to:

  • ✅ Name at least 6 tools (file, shell, web) with their function
  • ✅ Trace the sequence of tool calls an agent makes in a task in your project
  • ✅ Estimate how many files the agent can read before saturating the context window
  • ✅ Write a first draft of a CLAUDE.md (or AGENTS.md / .cursorrules) for a project you know
  • ✅ Identify what permissions your agent currently has and propose reasonable changes
  • ✅ Distinguish between "the agent requested to run X" and "the agent ran X" — and why it matters

If any aren't met at the end, go back to the corresponding capsule. Module 05 (how to direct the agent) and Module 07 (building your own agent) assume these 6 points.

Summary

This module transforms your understanding from "the agent has tools" to "these are the tools, this is how it uses them, and this is how I configure them."

What it covers:

  • The three categories of tools (file, shell, web)
  • How the agent explores your codebase (context gathering)
  • Context management for real projects
  • Configuration files and permissions

What it produces:

  • Technical vocabulary to discuss the agent's capabilities with your team
  • The ability to trace and predict the agent's tool calls
  • Your own CLAUDE.md / AGENTS.md / .cursorrules
  • A conscious permissions policy (not by default)

Why it matters:

  • You can't direct the agent if you don't know what tools it has
  • You can't optimize your workflow if you don't understand context gathering
  • The correct configuration dramatically improves the results
  • Permissions protect your project and your system

Next capsule: 02 — File operations, shell, and web search — the three categories of tools with concrete examples. We start with "what's in the box" before understanding how the agent decides which tool to use.

Additional Resources

  1. Anthropic: Claude Code Tools — Tools available in Claude Code
  2. Cursor Documentation — Tools in Cursor Agent
  3. GitHub Copilot Agent Mode — Tools in Copilot Agent
  4. Anthropic Tool Use Docs — How tool calling works in the Claude API
  5. OpenAI Function Calling Guide — OpenAI's API for tools
  6. Agentic Coding: Tool Reference — A catalog of tools by agent
← PreviousCoding Agents vs Chatbots: The Difference That MattersNext →File Operations, Shell, and Web Search: The Three Categories of Tools