Mastering Claude Agent SDK Tools

Turn a single-command chatbot into a dependable automation agent by giving it a toolbox of deterministic tools. With the Claude Agent SDK, tools convert model reasoning into repeatable actions: discover what’s wrong, change files safely, run commands to validate behavior, and record results. Earlier you had one tool — Bash. That lets an agent run one command and return output. Real projects require workflows: find files, inspect contents, make surgical edits, run validation, and produce a report. Tools let the model orchestrate those steps while the deterministic operations (file reads, edits, shell commands) do the exact work. Example quick trace

Grep "public-read" → main.tf:14
Edit main.tf (missing brace fixed)
Edit main.tf (set acl = "private")
Bash terraform validate → Success!

Why tools matter

A chatbot without tools only describes changes.
An agent with tools can inspect real files, perform exact edits, run commands, and save evidence — turning description into operation.
The SDK’s allowed-tools mechanism enforces least privilege: give the agent only the tools needed for each step.

What tools do (four kinds of work)

Discovery: find and read the project so the agent knows what to change.
- Glob — locate files by pattern.
- Read — open files with line numbers and partial reads for large files.
- Grep — search inside files and return matches with line numbers.
Modification: edit or create files.
- Edit — one exact replacement; surgical and requires reading first.
- MultiEdit — apply a set of edits atomically (all succeed or none do).
- Write — create a new file from scratch.
Execution:
- Bash — run shell commands (Terraform, AWS CLI, Git, tests).
Output:
- Write — produce documentation, reports, or READMEs as final artifacts.

A presentation-style graphic titled "Four Kinds of Work, One Toolbox" showing four rounded cards labeled Discovery, Modification, Execution, and Output with brief descriptions and colored tool tags like Glob, Read, Grep, Edit, MultiEdit, Write, and Bash. The cards are arranged in a two-by-two grid on a light gray background.

How the agent gets access to tools

Use an allowed tools list to control which tools are available for each step.
Add a cwd option so every tool runs inside the correct project folder.
This is a simple, strong safety control: a discovery step that only has Read and Grep cannot modify files.

Example options in Python

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-6",
    allowed_tools=["Read", "Glob", "Grep"],  # discovery only
    permission_mode="acceptEdits",
    cwd="/root/code/terraform-project",      # run inside the project
)

Principle: Make production agents 99% deterministic and 1% reasoning. The model decides which tool to use and what to pass it (the 1%). The tools perform deterministic operations that don’t hallucinate (the 99%): reading bytes from disk, returning grep matches with line numbers, and running the shell exactly as written.

Real example: fixing a broken Terraform project

Discover first
- Glob finds every .tf file in the folder.
- Read opens main.tf and shows a missing brace in a lifecycle block.
- Grep searches for risky settings (e.g., public-read) and returns matches with line numbers.
Plan edits
- Confirm the exact text to replace by reading the file (Edit requires an exact match).
- Decide whether changes are single-line fixes (Edit) or multiple related edits that must happen together (MultiEdit).
Make changes safely
- Use Edit for a precise, single replacement.
- Use MultiEdit when multiple updates must be atomic (for example, enabling encryption and versioning in the same commit).

Examples of edits

Fix a stray missing brace in a lifecycle block:

lifecycle {
  prevent_destroy = true
} # brace fixed

Apply server-side encryption and enable versioning together (use MultiEdit so both changes land atomically):

server_side_encryption_configuration {
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

versioning {
  enabled = true
}

When to use Edit vs MultiEdit

Tool	Use case	Notes
`Edit`	Single targeted fixes	Requires exact text match — read the file first.
`MultiEdit`	Multiple related updates applied atomically	If one edit would fail, none are applied — prevents half-completed fixes.
`Write`	Create new artifacts (README, deployment report)	Use at the end to record findings and next steps.

Validate and report — never auto-apply

After edits, run terraform validate with Bash.
Run terraform plan to produce a plan for human review.
The agent should stop before terraform apply; leave the plan for a person to approve. This preserves professional Terraform workflow and safety.

Typical workflow (end-to-end)

Discovery: Glob, Read, Grep.
Fix: Edit and MultiEdit.
Validate: Bash → terraform validate and terraform plan.
Document: Write → deployment report or README.
Human: review plan, then terraform apply manually.

Example run output

$ python terraform_workflow.py
✓ Edit · MultiEdit main.tf → 3 errors fixed
✓ Bash: terraform validate
Success! The configuration is valid.
✓ Bash: terraform plan → 2 to add (bucket, versioning)
✓ Write deployment_report.txt - Safe to deploy
terraform apply ← stopped; a human reviews first

Best practices and safety controls

Grant the least privilege: give the agent only the tools it needs per step.
Always read before editing; Edit demands an exact match.
Use MultiEdit for grouped changes so the repository never ends up in a half-broken state.
Validate and plan automatically, but require human approval for apply/deploy stages.
Keep cwd explicit so tools run inside the intended project directory.

References

Foundations

Advanced Patterns

Capstone

Mastering Claude Agent SDK Tools

Watch Video

Practice Lab