# Tool System Reference (/docs/verdent-for-vscode/advanced-features/tool-reference)
> Complete reference for Verdent's tool system
### What You'll Learn [#what-youll-learn]
Comprehensive reference for Verdent's built-in tool system, including file operations, search capabilities, command execution, and integration tools.
***
## Available Tools Overview [#available-tools-overview]
Verdent for VS Code provides a comprehensive toolkit for code manipulation, navigation, and external interaction.
| Tool | Purpose | Key Capabilities |
| ------------ | ------------------------- | ----------------------------------------------------------------------- |
| `file_read` | Read file contents | Supports line ranges for large files, works with all text formats |
| `file_edit` | Targeted modifications | Replace exact text matches, multiple replacements, preserves formatting |
| `file_write` | Create or overwrite files | Complete file creation/replacement, handles text content |
| Tool | Purpose | Key Capabilities |
| -------------- | --------------------------- | ------------------------------------------------------------ |
| `glob` | Pattern-based file search | Glob patterns (`**/*.ts`), exclude patterns, result limiting |
| `grep_content` | Content search with context | Regex support, context lines, case-insensitive options |
| `grep_file` | List files with matches | Quickly identify files before reading contents |
| `list_dir` | Directory structure | Show hierarchy, exclude patterns, depth control |
| Tool | Purpose | Key Capabilities |
| ---------------- | ----------------------- | -------------------------------------------------------------- |
| `bash` | Shell command execution | Timeout configuration, summary descriptions, command chaining |
| `spawn_subagent` | Delegate to specialists | Launch general, explorer, verifier, or code-reviewer subagents |
| `todo_update` | Track task progress | Manage task lists, update status, progress tracking |
| Tool | Purpose | Key Capabilities |
| ------------ | ----------------------- | ---------------------------------------------------------- |
| `web_search` | Internet search | Query execution, result count control, freshness filtering |
| `web_fetch` | Fetch and analyze pages | Retrieve content, extract information with queries |
***
## Tool Capabilities and Use Cases [#tool-capabilities-and-use-cases]
### file\_read [#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:**
```bash
# 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 [#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 [#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 [#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:**
```bash
**/*.tsx # All TypeScript React files
src/**/*.test.js # All test files in src
**/config.* # All config files anywhere
```
***
### grep\_content [#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:**
```bash
# 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 [#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 [#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 [#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:**
```bash
# 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 [#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 [#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 [#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 [#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
***
## File Format Support [#file-format-support]
Verdent works with all text-based file formats through its file operation tools.
| Category | Languages/Extensions |
| -------------- | --------------------------------------------------- |
| **Web** | JavaScript, TypeScript, HTML, CSS, SCSS, LESS |
| **Backend** | Python, Java, Go, Rust, C, C++, C#, Ruby, PHP, Perl |
| **Mobile** | Swift, Kotlin, Dart (Flutter), Objective-C |
| **Functional** | Haskell, Scala, Elixir, Clojure, F# |
| **Scripting** | Bash, PowerShell, Zsh, Fish |
| **Data** | SQL, R, Julia, MATLAB |
| Format | Common Examples |
| -------- | ------------------------------------------------------ |
| **JSON** | package.json, tsconfig.json, settings.json |
| **YAML** | docker-compose.yml, GitHub Actions, Kubernetes configs |
| **TOML** | Cargo.toml, pyproject.toml |
| **XML** | pom.xml, web.xml, config files |
| **INI** | .gitconfig, .editorconfig |
| **ENV** | .env files, environment configuration |
| **HCL** | Terraform configuration |
| Format | Use Cases |
| -------------------- | ------------------------------------- |
| **Markdown** | README.md, documentation files |
| **HTML** | Templates, web pages |
| **LaTeX** | Scientific documents, academic papers |
| **reStructuredText** | Python documentation |
| **AsciiDoc** | Technical documentation |
### Data Formats [#data-formats]
| Format | Description |
| ------------------- | --------------------------- |
| **CSV/TSV** | Tabular data files |
| **Text-based data** | Log files, data dumps |
| **JSON/YAML** | Structured data interchange |
### Build & Package Files [#build--package-files]
| File | Purpose |
| -------------------- | -------------------- |
| **Makefile** | Build automation |
| **package.json** | Node.js dependencies |
| **requirements.txt** | Python packages |
| **Gemfile** | Ruby gems |
| **Cargo.toml** | Rust packages |
| **build.gradle** | Gradle builds |
| Format Type | Examples | Editability |
| --------------------- | --------------------------- | --------------------- |
| **Images** | PNG, JPG, GIF, SVG (binary) | Not directly editable |
| **Videos** | MP4, AVI, MOV | Not directly editable |
| **Compiled binaries** | EXE, DLL, SO | Not directly editable |
| **Archives** | ZIP, TAR, GZ | Not directly editable |
| **Office documents** | DOCX, XLSX, PPTX | Not directly editable |
| **PDFs** | PDF files | Not directly editable |
Binary files may be referenced in code but cannot be modified through file tools.
***
## Programming Language Support [#programming-language-support]
Verdent provides comprehensive support for all text-based programming languages and frameworks.
| Language/Framework | Support Level | Common Use Cases |
| ------------------ | ------------- | ----------------------------------------------- |
| JavaScript | Excellent | Frontend logic, Node.js backends, tooling |
| TypeScript | Excellent | Type-safe web apps, large-scale projects |
| React | Excellent | Component-based UIs, hooks, state management |
| Vue | Excellent | Progressive web apps, single-file components |
| Angular | Excellent | Enterprise applications, TypeScript integration |
| Svelte | Very Good | Compiled components, reactive programming |
| HTML/CSS | Excellent | Markup, styling, responsive design |
| SCSS/LESS | Excellent | Advanced styling, variables, mixins |
| Language/Framework | Support Level | Common Use Cases |
| -------------------- | ------------- | ---------------------------------------------- |
| Python | Excellent | APIs, data processing, automation |
| Django/Flask/FastAPI | Excellent | Web frameworks, REST APIs |
| Node.js/Express | Excellent | JavaScript backends, microservices |
| Java/Spring | Excellent | Enterprise applications, Spring Boot |
| Go | Excellent | High-performance services, CLIs |
| Rust | Very Good | Systems programming, performance-critical code |
| C/C++ | Very Good | Systems, embedded, game engines |
| C# / .NET | Excellent | Windows apps, web services, Unity |
| Ruby/Rails | Very Good | Web applications, rapid development |
| PHP | Good | WordPress, Laravel, legacy apps |
| Language/Framework | Support Level | Common Use Cases |
| ------------------ | ------------- | ---------------------------- |
| Swift | Excellent | iOS/macOS native apps |
| Kotlin | Excellent | Android native apps |
| Dart/Flutter | Excellent | Cross-platform mobile apps |
| React Native | Excellent | JavaScript-based mobile apps |
| Objective-C | Good | Legacy iOS/macOS apps |
| Language | Support Level | Common Use Cases |
| -------- | ------------- | ---------------------------------------- |
| Python | Excellent | NumPy, Pandas, scikit-learn, TensorFlow |
| R | Very Good | Statistical analysis, data visualization |
| SQL | Excellent | Database queries, schema design |
| Julia | Good | Scientific computing, numerical analysis |
| Language | Support Level | Common Use Cases |
| -------- | ------------- | ---------------------------------- |
| C | Very Good | Systems programming, embedded |
| C++ | Very Good | Performance-critical applications |
| Rust | Very Good | Memory-safe systems programming |
| Go | Excellent | Concurrent systems, cloud services |
| Assembly | Good | Low-level optimization, debugging |
**Support Quality:** Common languages (JavaScript, Python, TypeScript) have stronger support due to extensive training data. Less common or domain-specific languages may have reduced support quality but remain functional.
***
## Usage Limits and Best Practices [#usage-limits-and-best-practices]
### file\_read Efficiency [#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
```bash
# 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 [#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 [#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 [#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
```bash
# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)
# Less efficient: Too broad
glob("**/*") # Returns thousands of results
```
***
### grep Strategy [#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 [#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)
```bash
# 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 [#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
Always review bash commands in Manual Accept Mode when working in shared codebases or production environments.
### Subagent Delegation Efficiency [#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 [#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 [#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
For files over 500 lines, always use line ranges with `file_read` to maintain optimal performance.
***
### Tool Timeout Defaults [#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 [#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
***
## See Also [#see-also]
Learn about specialized agents
Control tool execution with modes