Tool System Reference

file_read

Capabilities:

• Read complete file contents or specific line ranges
• Essential for understanding code before modifications
• Efficient handling of large files through range specification

Use Cases:

• Reading configuration files before editing
• Understanding existing implementation patterns
• Reviewing test files to understand coverage

Example:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

Capabilities:

• Precise text replacement using exact string matching
• Multiple replacement operations with multiple flag
• Preserves file structure and formatting

Use Cases:

• Updating function implementations
• Modifying configuration values
• Refactoring variable names across files

Best Practice: Use for targeted changes. For complete rewrites, use file_write instead.

file_write

Capabilities:

• Create new files from scratch
• Completely replace existing file contents
• Handle any text-based format

Use Cases:

• Generating new components or modules
• Creating configuration files
• Writing test files

Warning: Overwrites existing files completely. Use file_edit for partial modifications.

glob

Capabilities:

• Find files matching patterns: **/*.ts, src/**/*.js
• Filter by directory path
• Exclude patterns to narrow results
• Control result count

Use Cases:

• Finding all components in a project
• Locating test files
• Identifying configuration files across directories

Example Patterns:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

Capabilities:

• Search file contents using regex patterns
• Show context lines before/after matches (-B, -A flags)
• Case-insensitive searching
• Filter by file type using glob patterns

Use Cases:

• Finding function definitions
• Locating API endpoint implementations
• Searching for specific error messages
• Identifying security patterns

Example:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

Capabilities:

• List files containing pattern matches
• Faster than grep_content when you only need file locations
• Regex pattern support
• Glob filtering for file types

Use Cases:

• Identifying which files need refactoring
• Finding files that import specific modules
• Locating files with deprecated patterns

Best Practice: Use grep_file first to identify relevant files, then file_read for detailed examination.

list_dir

Capabilities:

• Display directory hierarchy
• Control depth with max_depth parameter
• Exclude patterns to filter output

Use Cases:

• Understanding project structure
• Verifying directory organization
• Finding specific subdirectories

bash

Capabilities:

• Execute shell commands
• Maximum timeout: 120 seconds (2 minutes, hard limit)
• Chain commands with && for dependencies
• Provide descriptive summaries for clarity

Use Cases:

• Running tests
• Building projects
• Installing dependencies
• Git operations
• Database migrations

Example:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

Security: Commands execute with user permissions. Review commands in Manual Accept Mode.

spawn_subagent

Capabilities:

• Launch specialized subagents with isolated contexts
• Types: explorer, verifier, code-reviewer
• Delegate complex tasks without polluting main context
• Parallel subagent execution for efficiency

Use Cases:

• explorer: Search large codebases for patterns
• verifier: Validate implementation logic
• code-reviewer: Security and quality assessment

Best Practice: Delegate exploratory research to Explorer subagent to preserve main conversation context.

todo_update

Capabilities:

• Create and manage task lists
• Update task status (pending, in_progress, completed)
• Track progress across complex implementations

Use Cases:

• Breaking down multi-step features
• Tracking refactoring progress
• Managing migration tasks

web_search

Capabilities:

• Query internet search engines
• Control result count
• Filter by freshness (recent days)

Use Cases:

• Finding documentation for unfamiliar APIs
• Researching error messages
• Checking current best practices

web_fetch

Capabilities:

• Retrieve web page contents
• Analyze content with specific queries
• Extract structured information

Use Cases:

• Reading documentation pages
• Analyzing API documentation
• Extracting examples from tutorials

Data Formats

Build & Package Files

file_read Efficiency

Best Practices:

• Use line ranges for files over 500 lines to avoid context overload
• Read only relevant sections needed for the task
• For large files, use grep_content first to identify relevant line numbers

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

file_edit Precision

Best Practices:

• Ensure exact string matches to avoid failed edits
• For multiple similar changes, use multiple=true flag
• Verify file paths before editing

file_write Safety

Best Practices:

• Double-check paths to prevent accidental overwrites
• Use for new files or complete rewrites only
• For modifications, prefer file_edit for safety

glob Pattern Specificity

Best Practices:

• Use specific patterns to narrow scope: src/**/*.ts instead of **/*
• Exclude directories with exclude patterns: !**/node_modules/**
• Limit results to prevent overwhelming output

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

grep Strategy

Recommended Workflow:

1. Use grep_file to identify relevant files
2. Read specific files with file_read
3. Use grep_content when you need surrounding context

Performance Tips:

• Regex patterns may take longer than literal strings
• Case-insensitive searches are slower
• Limit context lines (-A, -B) to what's necessary

bash Best Practices

Safe Command Execution:

• Provide clear summaries for command descriptions
• Set appropriate timeouts for long-running operations
• Chain dependent commands with &&
• Review destructive commands carefully (rm, drop, truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

Security Considerations

Critical Safety Rules:

• Commands execute with user permissions
• Never run untrusted commands
• Use Manual Accept Mode for review in shared codebases
• Avoid commands that expose credentials or sensitive data

Subagent Delegation Efficiency

When to Use Subagents:

• Explorer: Codebase searches, architecture questions (saves main context)
• Verifier: Quick validation checks (isolated verification)
• Code-reviewer: Security and quality reviews (detailed analysis)
• General: Complex multi-step tasks (parallel execution)

Best Practice: Delegate exploratory and research tasks to subagents to preserve main conversation context for active development work.

Context Management

Strategic Tool Usage:

• Read files strategically - only what's needed
• Use subagents for background research
• Monitor context consumption during long sessions
• Break complex operations into steps with todo_update

Efficient Workflows:

1. Planning: Use glob/grep to identify scope
2. Reading: Read only relevant files/sections
3. Execution: Delegate to subagents when appropriate
4. Verification: Quick checks with Verifier subagent

File Size Limits

Large File Handling: Very large files (>10,000 lines) should be read in sections to avoid:

• Context window exhaustion
• Slow response times
• Memory issues

Tool Timeout Defaults

Tool Limits:

• Bash timeout: 120 seconds (2 minutes) maximum
• File operations: No size limits (large files automatically read in batches)
• Large file handling: Files >256KB return only first 256KB of content
• Search results: No limits on glob or grep_content results
• Concurrent subagents: No limits on parallel execution

Timeout Configuration:

• Set explicit timeouts for long-running operations
• Monitor for hanging processes
• Commands exceeding 2-minute timeout will be terminated

Concurrent Operations

Parallel Execution: Multiple subagents can run in parallel for faster complex operations. The main agent automatically handles coordination.

Performance Benefits:

• Reduced total execution time for multi-step tasks
• Efficient resource utilization
• Automatic task orchestration
• No limits on number of concurrent subagents