Go back

Claude Code Built-in Tools Reference

This is a guide I created while exploring the built-in tools Claude Code ships with and how it’s trained/prompted to use them. Included below is every built-in tool, their parameters, usage patterns, and examples. This was basically all written by prompting Claude Code itself.

Table of Contents

Open Table of Contents

1. Task

Purpose: Launch specialized sub-agents for complex, multi-step tasks that require autonomous work.

Available Agent Types:

Parameters:

When to Use:

When NOT to Use:

Example:

{
  "subagent_type": "general-purpose",
  "description": "Find authentication implementation",
  "prompt": "Search the codebase to find where user authentication is implemented. Look for login functions, JWT handling, and session management. Return the file paths and a summary of how authentication works."
}

Key Notes:

2. Bash

Purpose: Execute shell commands in a persistent bash session.

Parameters:

When to Use:

When NOT to Use:

Examples:

Basic command:

{
  "command": "git status",
  "description": "Check git repository status"
}

With timeout:

{
  "command": "npm run build",
  "description": "Build production bundle",
  "timeout": 300000
}

Background process:

{
  "command": "npm run dev",
  "description": "Start development server",
  "run_in_background": true
}

Chained commands (sequential with &&):

{
  "command": "git add . && git commit -m \"Update features\" && git push",
  "description": "Stage, commit, and push changes"
}

Command with paths containing spaces:

{
  "command": "cd \"/path/with spaces/\" && ls",
  "description": "List files in directory with spaces"
}

Git Commit Best Practices:

  1. Run git status, git diff, and git log in parallel
  2. Draft commit message following repo style
  3. Add files and commit with co-authorship footer:
git commit -m "$(cat <<'EOF'
Your commit message here.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Pull Request Creation:

  1. Run git status, git diff, and git log [base-branch]...HEAD in parallel
  2. Draft PR summary from ALL commits (not just latest)
  3. Push and create PR:
gh pr create --title "PR title" --body "$(cat <<'EOF'
## Summary
- Bullet point 1
- Bullet point 2

## Test plan
- [ ] Test item 1
- [ ] Test item 2

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

3. Glob

Purpose: Fast file pattern matching for finding files by name patterns.

Parameters:

Pattern Examples:

Examples:

Find all TypeScript files:

{
  "pattern": "**/*.ts"
}

Find config files in specific directory:

{
  "pattern": "*.config.{js,ts}",
  "path": "/Users/project/root"
}

Find React components:

{
  "pattern": "src/components/**/*.tsx"
}

Key Notes:

4. Grep

Purpose: Powerful content search built on ripgrep for finding text/code patterns in files.

Parameters:

Pattern Syntax:

Examples:

Find files containing pattern:

{
  "pattern": "function authenticate",
  "output_mode": "files_with_matches"
}

Show matching lines with context:

{
  "pattern": "TODO",
  "output_mode": "content",
  "-n": true,
  "-C": 2
}

Case-insensitive search in TypeScript files:

{
  "pattern": "errorhandler",
  "-i": true,
  "type": "ts",
  "output_mode": "content"
}

Count occurrences:

{
  "pattern": "console\\.log",
  "output_mode": "count"
}

Search with glob filter:

{
  "pattern": "import.*React",
  "glob": "*.tsx",
  "output_mode": "content"
}

Multiline pattern matching:

{
  "pattern": "struct \\{[\\s\\S]*?field",
  "multiline": true,
  "output_mode": "content"
}

Limited results:

{
  "pattern": "export function",
  "output_mode": "content",
  "head_limit": 10
}

5. Read, 6. Edit, 7. Write

Read

Purpose: Read files from the filesystem.

Parameters:

Supported File Types:

Examples:

Read entire file:

{
  "file_path": "/Users/vivektrivedy/Desktop/personal_website/vtrivedy_website/src/config.ts"
}

Read specific line range:

{
  "file_path": "/path/to/large/file.log",
  "offset": 1000,
  "limit": 100
}

Read image:

{
  "file_path": "/var/folders/tmp/Screenshot.png"
}

Key Notes:

Edit

Purpose: Perform exact string replacements in files.

Parameters:

Requirements:

Line Number Prefix Format:

[spaces][line_number][tab][actual_content]

Only include [actual_content] in old_string/new_string.

Examples:

Simple replacement:

{
  "file_path": "/path/to/file.ts",
  "old_string": "const port = 3000;",
  "new_string": "const port = 4321;"
}

Multi-line replacement:

{
  "file_path": "/path/to/component.tsx",
  "old_string": "export default function Header() {\n  return <h1>Old Title</h1>;\n}",
  "new_string": "export default function Header() {\n  return <h1>New Title</h1>;\n}"
}

Replace all occurrences (renaming):

{
  "file_path": "/path/to/file.ts",
  "old_string": "oldFunctionName",
  "new_string": "newFunctionName",
  "replace_all": true
}

Common Mistakes to Avoid:

Write

Purpose: Write or overwrite files.

Parameters:

Requirements:

Examples:

Create new file:

{
  "file_path": "/path/to/new/file.ts",
  "content": "export const API_URL = 'https://api.example.com';\n"
}

Overwrite existing file:

{
  "file_path": "/path/to/existing/config.json",
  "content": "{\n  \"version\": \"2.0\",\n  \"enabled\": true\n}\n"
}

8. NotebookEdit

Purpose: Edit Jupyter notebook (.ipynb) cells.

Parameters:

Examples:

Replace cell content:

{
  "notebook_path": "/path/to/notebook.ipynb",
  "cell_id": "abc123",
  "new_source": "import pandas as pd\ndf = pd.read_csv('data.csv')\ndf.head()"
}

Insert new code cell:

{
  "notebook_path": "/path/to/notebook.ipynb",
  "cell_id": "xyz789",
  "cell_type": "code",
  "edit_mode": "insert",
  "new_source": "# New analysis step\nresult = df.groupby('category').sum()"
}

Delete cell:

{
  "notebook_path": "/path/to/notebook.ipynb",
  "cell_id": "def456",
  "edit_mode": "delete",
  "new_source": ""
}

9. WebFetch, 10. WebSearch

WebFetch

Purpose: Fetch and process web content with AI analysis.

Parameters:

Features:

Examples:

Fetch documentation:

{
  "url": "https://docs.astro.build/en/getting-started/",
  "prompt": "Extract the commands needed to create a new Astro project and start the dev server"
}

Analyze article:

{
  "url": "https://example.com/blog/best-practices",
  "prompt": "Summarize the key best practices mentioned in this article"
}

Check API reference:

{
  "url": "https://api-docs.example.com/v2/authentication",
  "prompt": "What are the authentication methods supported and their required parameters?"
}

Key Notes:

WebSearch

Purpose: Search the web for current information beyond Claude’s knowledge cutoff.

Parameters:

Availability: US only

Examples:

Basic search:

{
  "query": "Astro 4.0 new features 2025"
}

Search specific domains:

{
  "query": "TypeScript best practices",
  "allowed_domains": ["typescript-lang.org", "github.com"]
}

Exclude domains:

{
  "query": "React hooks tutorial",
  "blocked_domains": ["pinterest.com", "youtube.com"]
}

Key Notes:

11. TodoWrite

Purpose: Create and manage structured task lists for tracking progress.

Parameters:

When to Use:

When NOT to Use:

Critical Rules:

Examples:

Create initial todo list:

{
  "todos": [
    {
      "content": "Search codebase for authentication logic",
      "activeForm": "Searching codebase for authentication logic",
      "status": "in_progress"
    },
    {
      "content": "Implement OAuth2 flow",
      "activeForm": "Implementing OAuth2 flow",
      "status": "pending"
    },
    {
      "content": "Add authentication tests",
      "activeForm": "Adding authentication tests",
      "status": "pending"
    }
  ]
}

Update progress:

{
  "todos": [
    {
      "content": "Search codebase for authentication logic",
      "activeForm": "Searching codebase for authentication logic",
      "status": "completed"
    },
    {
      "content": "Implement OAuth2 flow",
      "activeForm": "Implementing OAuth2 flow",
      "status": "in_progress"
    },
    {
      "content": "Add authentication tests",
      "activeForm": "Adding authentication tests",
      "status": "pending"
    }
  ]
}

12. ExitPlanMode

Purpose: Exit plan mode after presenting an implementation plan.

Parameters:

When to Use:

When NOT to Use:

Example:

{
  "plan": "## Implementation Plan\n\n1. Create authentication middleware in `src/middleware/auth.ts`\n2. Add JWT verification logic\n3. Protect API routes with middleware\n4. Add tests for authentication flow\n\nShall I proceed with this plan?"
}

13. BashOutput, 14. KillShell

BashOutput

Purpose: Retrieve output from running or completed background bash shells.

Parameters:

Returns:

Example:

{
  "bash_id": "shell_12345",
  "filter": "ERROR|WARN"
}

Key Notes:

KillShell

Purpose: Terminate a running background bash shell.

Parameters:

Example:

{
  "shell_id": "shell_12345"
}

15. SlashCommand

Purpose: Execute slash commands within the conversation.

Parameters:

Restrictions:

Example:

{
  "command": "/help"
}

Tool Usage Patterns & Best Practices

Batch Operations

Always batch independent tool calls in a single response for optimal performance.

Example - Multiple file reads:

Call Read on file1.ts, file2.ts, file3.ts in single message

Example - Parallel git commands:

Call Bash("git status") and Bash("git diff") in single message

File Operations Workflow

  1. Search for files: Use Glob (not find/ls)
  2. Search content: Use Grep (not bash grep/rg)
  3. Read files: Use Read (not cat/head/tail)
  4. Edit files: Use Edit (not sed/awk)
  5. Write files: Use Write (not echo >/heredoc)

Complex Task Workflow

  1. Use TodoWrite to plan and track tasks
  2. Use Task agent for multi-step research
  3. Use Bash for terminal operations only
  4. Batch independent operations together
  5. Mark todos completed immediately after finishing

Background Process Management

  1. Start process: Bash with run_in_background: true
  2. Monitor output: BashOutput with bash_id
  3. Filter if needed: Use filter parameter with regex
  4. Terminate when done: KillShell with shell_id

Searching Strategy

Communication

Examples: Complete Workflows

Workflow 1: Add New Feature

1. TodoWrite: Plan the feature tasks
2. Grep: Find related existing implementations
3. Read: Read relevant files (batch multiple)
4. Edit: Modify existing files (or Write for new files)
5. Bash: Run tests
6. TodoWrite: Mark tasks completed
7. Bash: Commit changes (if requested)

Workflow 2: Debug Issue

1. TodoWrite: Create debugging task list
2. Grep: Search for error messages/patterns
3. Read: Read files with issues (batch multiple)
4. Bash: Run failing tests/reproduce issue
5. Edit: Apply fixes
6. Bash: Verify fix with tests
7. TodoWrite: Mark completed

Workflow 3: Research Codebase

1. Task: Launch general-purpose agent with research prompt
   (Agent will autonomously use Grep, Glob, Read to explore)
2. Agent returns findings
3. Present summary to user

Workflow 4: Refactor Code

1. TodoWrite: Break down refactoring tasks
2. Grep: Find all occurrences of code to refactor
3. Read: Read affected files (batch multiple)
4. Edit: Apply refactoring with replace_all for renames
5. Bash: Run tests and type checking
6. TodoWrite: Mark tasks completed

Tool Selection Quick Reference

TaskUse This ToolNOT This
Find files by nameGlobBash(find/ls)
Search contentGrepBash(grep/rg)
Read fileReadBash(cat/head/tail)
Edit fileEditBash(sed/awk)
Create fileWriteBash(echo >)
Run tests/buildsBashN/A
Multi-step researchTaskMultiple manual searches
Track complex tasksTodoWriteComments/memory
Fetch web contentWebFetchBash(curl)
Search webWebSearchWebFetch with search engine
Background processBash(run_in_background) + BashOutputBash with &

Common Antipatterns to Avoid

❌ Don’t: Use bash for file operations

cat src/config.ts

✅ Do: Use Read tool

{"file_path": "src/config.ts"}

❌ Don’t: Use echo for communication

echo "Now processing files..."

✅ Do: Output text directly to user

Now processing files...

❌ Don’t: Make sequential tool calls when independent

Call Read on file1, wait, then Read on file2, wait, then Read on file3

✅ Do: Batch independent calls

Call Read on file1, file2, file3 in single message

❌ Don’t: Forget to use TodoWrite for complex tasks

Start working without planning

✅ Do: Plan first with TodoWrite

{"todos": [...]}

❌ Don’t: Mark todos completed before actually finishing

{"status": "completed"} // but tests are failing

✅ Do: Only mark completed when fully done

{"status": "in_progress"} // keep working until tests pass

That’s all for now, I’ll try to update this guide with more tools or useful patterns as they come out. But really this is mostly just a reference to look back on when I need to.

Share this post on:
Share this post via WhatsAppShare this post on FacebookShare this post on XShare this post via TelegramShare this post on PinterestShare this post via email
Next Post
Agent Building Resources