Tool Usage Overview

VJSP implements a sophisticated tool system that allows AI models to interact with your development environment in a controlled and secure manner. This document explains how tools work, when they are invoked, and how they are managed.

Core Concepts

Tool Groups

Tools are logically grouped by functionality:

Category	Purpose	Tools	Common Use Cases
Read Group	Filesystem reading and searching	read_file, search_files, list_files, list_code_definition_names	Code exploration and analysis
Edit Group	Filesystem modifications	apply_diff, write_to_file	Code changes and file operations
Browser Group	Web automation	browser_action	Web testing and interaction
Command Group	System command execution	execute_command	Running scripts, building projects
MCP Group	External tool integration	use_mcp_tool, access_mcp_resource	Specialized capabilities via external servers
Workflow Group	Mode and task management	switch_mode, new_task, ask_followup_question, attempt_completion	Context switching and task organization

Always-Available Tools

Certain tools are accessible in any mode:

• ask_followup_question: Collect additional information from the user
• attempt_completion: Mark a task as complete
• switch_mode: Change operating mode
• new_task: Create subtasks
• update_todo_list: Manage step-by-step task tracking

Available Tools

Read Tools

These tools help VJSP understand your code and project:

• read_file – Inspect file contents
• search_files – Find patterns across multiple files
• list_files – Map project file structure
• list_code_definition_names – Generate a code structure map

Edit Tools

These tools help VJSP modify your code:

• apply_diff – Make precise code modifications
• write_to_file – Create new files or fully overwrite existing ones

Browser Tools

These tools help VJSP interact with web applications:

• browser_action – Automate browser interactions

Command Tools

These tools help VJSP execute commands:

• execute_command – Run system commands and programs

MCP Tools

These tools help VJSP connect to external services:

• use_mcp_tool – Use specialized external tools
• access_mcp_resource – Access external data sources

Workflow Tools

These tools help manage conversation and task flow:

• ask_followup_question – Gather additional information from you
• attempt_completion – Present final results
• switch_mode – Switch to a different mode for specialized tasks
• new_task – Create new subtasks
• update_todo_list – Track task progress via step-by-step checklists

Tool Invocation Mechanism

When Tools Are Called

Tools are invoked under specific conditions:

1. Direct Task Requirements

   • When a specific operation is needed to complete an LLM-determined task
   • In response to user requests
   • Within automated workflows

2. Mode-Based Availability

   • Different modes enable different tool sets
   • Switching modes can change tool availability
   • Some tools are restricted to specific modes

3. Context-Dependent Invocation

   • Based on the current state of the workspace
   • In response to system events
   • During error handling and recovery

Decision Process

The system uses a multi-step process to determine tool availability:

1. Mode Validation

   isToolAllowedForMode(
       tool: string,
       modeSlug: string,
       customModes: ModeConfig[],
       toolRequirements?: Record<string, boolean>,
       toolParams?: Record<string, any>
   )

2. Requirement Checks

   • System capability verification
   • Resource availability
   • Permission validation

3. Parameter Validation

   • Presence of required parameters
   • Parameter type checking
   • Value validation

Technical Implementation

Tool Call Handling

1. Initialization

   • Validate tool name and arguments
   • Check mode compatibility
   • Verify requirements

2. Execution

   const toolCall = {
       type: "tool_call",
       name: chunk.name,
       arguments: chunk.input,
       callId: chunk.callId
   }

3. Result Handling

   • Determine success/failure
   • Format results
   • Handle errors

Security and Permissions

1. Access Control

   • Filesystem restrictions
   • Command execution limits
   • Network access controls

2. Validation Layers

   • Tool-specific validation
   • Mode-based restrictions
   • System-level checks

Mode Integration

Mode-Based Tool Access

Tools are made available based on the current mode:

• Code Mode: Full access to filesystem tools, code editing capabilities, and command execution
• Ask Mode: Limited to read tools and information-gathering capabilities; no filesystem modifications
• Architect Mode: Design-oriented tools and documentation capabilities with limited execution permissions
• Custom Modes: Configurable tool access for specialized workflows

Mode Switching

1. Process

   • Save current mode state
   • Update tool availability
   • Perform context switch

2. Impact on Tools

   • Changes in available tool set
   • Permission adjustments
   • Context preservation

Best Practices

Tool Usage Guidelines

1. Efficiency

   • Use the most appropriate tool for the task
   • Avoid redundant tool calls
   • Batch operations whenever possible

2. Security

   • Validate inputs before invoking tools
   • Use the principle of least privilege
   • Follow security best practices

3. Error Handling

   • Implement proper error checking
   • Provide meaningful error messages
   • Handle failures gracefully

Common Patterns

1. Information Gathering

[ask_followup_question](/feature/tools/ask_followup_question) → [read_file](/feature/tools/read_file) → [search_files](/feature/tools/search_files)

2. Code Modification

[read_file](/feature/tools/read_file) → [apply_diff](/feature/tools/apply_diff) → [attempt_completion](/feature/tools/attempt_completion)

3. Task Management

[new_task](/feature/tools/new_task) → [switch_mode](/feature/tools/switch_mode) → [execute_command](/feature/tools/execute_command)

4. Progress Tracking

   [update_todo_list](/feature/tools/update_todo_list) → [execute_command](/feature/tools/execute_command) → [update_todo_list](/feature/tools/update_todo_list)

Error Handling and Recovery

Error Types

1. Tool-Specific Errors

   • Parameter validation failures
   • Execution errors
   • Resource access issues

2. System Errors

   • Permission denied
   • Resource unavailable
   • Network failures

3. Context Errors

   • Invalid mode for tool
   • Missing requirements
   • State inconsistency

Recovery Strategies

1. Automatic Recovery

   • Retry mechanisms
   • Fallback options
   • State restoration

2. User Intervention

   • Error notifications
   • Recovery suggestions
   • Manual intervention options