Tool System Reference

​

glob

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

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

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

​

grep_content

• 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

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

# 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

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

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

​

list_dir

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

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

​

bash

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

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

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

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

​

spawn_subagent

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

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

​

todo_update

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

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

​

web_search

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

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

​

web_fetch

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

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

​

Data Formats

​

Build & Package Files

​

glob Pattern Specificity

• 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

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

• 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

• 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

• 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

• 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)

​

Context Management

• 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

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

• Context window exhaustion
• Slow response times
• Memory issues

​

Tool Timeout Defaults

• 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

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

​

Concurrent Operations

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