Claude Code Built-in Tools Reference

Complete reference for all default tools available in Claude Code CLI.

Overview

Claude Code provides 18 built-in tools organized into six categories:

File Operations

Read

Purpose: Read file contents from the filesystem.

Parameters:

Behavior:

• Reads up to 2000 lines by default
• Returns content with line numbers (cat -n format)
• Truncates lines longer than 2000 characters
• Can read images (PNG, JPG) and display them visually
• Can read PDFs with text and visual content extraction
• Can read Jupyter notebooks (.ipynb) with all cells and outputs

Best Practices:

• Always use absolute paths, not relative paths
• Use offset and limit for files larger than 2000 lines
• Read files before using Edit or Write tools
• Combine with Grep for targeted reading

Example:

Read /Users/project/src/main.js
Read /Users/project/data.json offset=100 limit=50

Write

Purpose: Create new files or completely overwrite existing files.

Parameters:

Behavior:

• Overwrites entire file content (not append)
• Creates parent directories if needed
• Creates a checkpoint before writing (allows revert)
• Requires permission (ask/allow in settings)

Best Practices:

• Use for creating new files from scratch
• Use Edit tool instead for modifying existing files
• Must Read existing files before overwriting
• Never use bash echo/cat for file writing

Permission Required: Yes

Edit

Purpose: Make targeted replacements in files without overwriting the entire file.

Parameters:

Behavior:

• Performs exact text matching (case-sensitive, whitespace-sensitive)
• Fails if old_string is not unique (unless replace_all is true)
• Creates checkpoint before editing
• Shows context around changes

Best Practices:

• Must Read the file first before editing
• Preserve exact indentation from the file
• Include surrounding context to make old_string unique
• Use replace_all for renaming variables across the file

Permission Required: Yes

Example:

Edit /path/to/file.js
  old_string: "function oldName()"
  new_string: "function newName()"

MultiEdit

Purpose: Make multiple sequential find-and-replace operations in a single file atomically.

Parameters:

Each edit in the array contains:

• old_string: Text to find
• new_string: Replacement text

Behavior:

• Applies all edits sequentially in order
• Atomic operation (all succeed or all fail)
• Single checkpoint for all edits

Best Practices:

• Use for multiple related changes in one file
• More efficient than multiple Edit calls
• Order matters - edits apply sequentially

Permission Required: Yes

NotebookEdit

Purpose: Modify Jupyter notebook cells (.ipynb files).

Parameters:

Behavior:

• replace: Replace cell content (default)
• insert: Add new cell after specified cell_id
• delete: Remove the specified cell
• Preserves notebook structure and metadata

Best Practices:

• Use for Jupyter notebook modifications
• Maintain logical flow between cells
• Test notebook with kernel after modifications

Permission Required: Yes

Search & Discovery

Glob

Purpose: Find files matching glob patterns without searching file contents.

Parameters:

Supported Patterns:

Behavior:

• Returns file paths sorted by modification time
• Works with any codebase size
• Fast file discovery

Best Practices:

• Use before Read for efficient file discovery
• Perform multiple searches in parallel when useful
• Use **/* for recursive search

Permission Required: No

Examples:

Glob pattern="**/*.js"                    # All JavaScript files
Glob pattern="src/**/*.ts"                # TypeScript in src/
Glob pattern="**/test/**/*.spec.js"       # Test spec files
Glob pattern="*.{js,ts,jsx,tsx}"          # Multiple extensions

Grep

Purpose: Search file contents using regex patterns (powered by ripgrep).

Parameters:

Output Modes:

Behavior:

• Uses ripgrep (highly optimized)
• Full regex syntax support
• NEVER use bash grep or rg - always use this tool

Best Practices:

• Use files_with_matches for initial discovery
• Use content mode with -C for context
• Combine with type or glob to narrow scope
• Use head_limit to avoid overwhelming output

Permission Required: No

Examples:

Grep pattern="function.*auth" type="js"           # Auth functions in JS
Grep pattern="TODO|FIXME" output_mode="content"   # Find TODOs with context
Grep pattern="import.*React" glob="**/*.jsx"      # React imports
Grep pattern="class.*Error" -C=3                  # Error classes with context

LS

Purpose: List directory contents.

Parameters:

Behavior:

• Lists files and directories at the specified path
• Can filter out patterns with ignore parameter

Best Practices:

• Use for exploring directory structure
• Use Glob instead for pattern-based file finding
• Never use bash ls command

Permission Required: No

Execution

Bash

Purpose: Execute shell commands in a persistent bash session.

Parameters:

Behavior:

• Working directory persists across commands
• Environment variables do NOT persist between commands
• Default timeout: 120000ms (2 minutes)
• Output truncated if exceeds 30000 characters
• Supports pipes, redirects, and complex shell syntax

Best Practices:

• Use && to chain dependent commands
• Use absolute paths in scripts
• Quote file paths with spaces: cd "/path with spaces"
• Use for: git, npm, docker, pytest, build tools
• NEVER use for: find, grep, cat, head, tail, sed, awk, echo

Prohibited Commands: Use dedicated tools instead:

Permission Required: Yes (configurable with patterns)

Examples:

Bash command="npm test"
Bash command="git status"
Bash command="cd /project && npm install && npm run build"
Bash command="python script.py" timeout=300000
Bash command="npm run dev" run_in_background=true

KillShell

Purpose: Stop a running background bash shell.

Parameters:

Behavior:

• Stops background bash execution
• Cleans up task tracking
• Shell IDs visible with /tasks command

Permission Required: Yes

Web & Network

WebFetch

Purpose: Fetch and analyze content from URLs.

Parameters:

Behavior:

• Automatically upgrades HTTP to HTTPS
• Converts HTML to markdown
• Processes content with small, fast AI model
• 15-minute cache for repeated access
• Handles redirects (provides new URL to fetch)

Best Practices:

• Provide clear, specific prompts
• Use for documentation and reference material
• If redirected to different host, make new request with redirect URL

Permission Required: Yes

Example:

WebFetch url="https://docs.example.com/api" prompt="List available endpoints"
WebFetch url="https://github.com/user/repo" prompt="What is the project purpose?"

WebSearch

Purpose: Search the web for current information.

Parameters:

Behavior:

• Returns search results with markdown hyperlinks
• Provides up-to-date information beyond knowledge cutoff
• Only available in the US

Best Practices:

• Include year in queries for recent information
• Use domain filtering for specific sources
• Always cite sources in responses

Permission Required: Yes

Example:

WebSearch query="React 2026 best practices"
WebSearch query="Claude API updates" allowed_domains=["anthropic.com"]

Task Management

Task

Purpose: Launch specialized sub-agents for complex, multi-step tasks.

Parameters:

Available Agent Types:

Behavior:

• Spawns agent with fresh, isolated context
• Agent context doesn't bloat main conversation
• Returns summarized results when complete
• Can be resumed with agent ID

Best Practices:

• Use for complex tasks requiring multiple steps
• Launch multiple agents in parallel when possible
• Use Explore agent for codebase searches
• Use haiku model for quick, simple tasks

Permission Required: No

Example:

Task subagent_type="Explore" description="Find auth handlers"
  prompt="Find all files that handle user authentication"

Task subagent_type="Plan" description="Plan refactoring"
  prompt="Create a plan to refactor the database module"

TodoWrite

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

Parameters:

Each todo item contains:

Behavior:

• Exactly ONE task should be in_progress at a time
• Mark tasks complete immediately after finishing
• Task list visible in UI

When to Use:

• Complex multi-step tasks (3+ steps)
• User provides multiple tasks
• Non-trivial implementations
• After receiving new instructions

When NOT to Use:

• Single, straightforward tasks
• Trivial operations (< 3 steps)
• Purely conversational requests

Permission Required: No

Example:

{
  "todos": [
    {"content": "Run tests", "activeForm": "Running tests", "status": "completed"},
    {"content": "Fix type errors", "activeForm": "Fixing type errors", "status": "in_progress"},
    {"content": "Update documentation", "activeForm": "Updating documentation", "status": "pending"}
  ]
}

Planning & Interaction

ExitPlanMode

Purpose: Signal completion of planning phase and request user approval.

Parameters:

Behavior:

• Reads plan from the plan file (already written)
• Signals readiness for user review
• Can request semantic permissions for bash commands

Best Practices:

• Write plan to plan file before calling
• Use for implementation tasks requiring approval
• Request specific, scoped permissions

Permission Required: Yes (user approval)

AskUserQuestion

Purpose: Ask users questions to gather requirements or clarify ambiguity.

Parameters:

Each question contains:

Each option contains:

Behavior:

• Users can always select "Other" for custom input
• Use multiSelect: true for non-mutually-exclusive choices
• Put recommended option first with "(Recommended)" suffix

Best Practices:

• Use sparingly to avoid interrupting workflow
• Provide clear, specific questions
• Offer reasonable default choices

Permission Required: No

Skill

Purpose: Execute a custom skill (slash command) within the conversation.

Parameters:

Behavior:

• Invokes skill immediately as first action
• Only uses skills listed in available skills
• Does not invoke already-running skills

Permission Required: Varies by skill

Permission Configuration

Permission Modes

Toggle with Shift+Tab:

Configuring Permissions

In .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(git:*)",
      "Write(src/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(.env*)"
    ]
  }
}

Permission Patterns

Quick Reference

Sources

Official:

• Claude Code CLI Reference
• Claude Code GitHub Repository

Community references (unofficial, may be outdated):

• Claude Code Built-in Tools Reference
• Claude Code Tools and System Prompt