Roo Code 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're called, and how they're managed.
Tools are organized into logical groups based on their functionality:
| Category | Purpose | Tools | Common Use |
|---|---|---|---|
| Read Group | File system reading and searching | read_file, search_files, list_files, list_code_definition_names | Code exploration and analysis |
| Edit Group | File system modifications | apply_diff, insert_content, search_and_replace, write_to_file | Code changes and file manipulation |
| 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 functionality through external servers |
| Workflow Group | Mode and task management | switch_mode, new_task, ask_followup_question, attempt_completion | Context switching and task organization |
Certain tools are accessible regardless of the current mode:
- ask_followup_question: Gather additional information from users
- attempt_completion: Signal task completion
- switch_mode: Change operational modes
- new_task: Create subtasks
These tools help Roo understand your code and project:
- read_file - Examines the contents of files
- search_files - Finds patterns across multiple files
- list_files - Maps your project's file structure
- list_code_definition_names - Creates a structural map of your code
These tools help Roo make changes to your code:
- apply_diff - Makes precise, surgical changes to your code
- insert_content - Adds new lines of content without modifying existing lines
- search_and_replace - Finds and replaces text or regex patterns within a file
- write_to_file - Creates new files or completely rewrites existing ones
These tools help Roo interact with web applications:
- browser_action - Automates browser interactions
These tools help Roo execute commands:
- execute_command - Runs system commands and programs
These tools help Roo connect with external services:
- use_mcp_tool - Uses specialized external tools
- access_mcp_resource - Accesses external data sources
These tools help manage the conversation and task flow:
- ask_followup_question - Gets additional information from you
- attempt_completion - Presents final results
- switch_mode - Changes to a different mode for specialized tasks
- new_task - Creates a new subtask
Tools are invoked under specific conditions:
-
Direct Task Requirements
- When specific actions are needed to complete a task as decided by the LLM
- In response to user requests
- During automated workflows
-
Mode-Based Availability
- Different modes enable different tool sets
- Mode switches can trigger tool availability changes
- Some tools are restricted to specific modes
-
Context-Dependent Calls
- Based on the current state of the workspace
- In response to system events
- During error handling and recovery
The system uses a multi-step process to determine tool availability:
-
Mode Validation
isToolAllowedForMode( tool: string, modeSlug: string, customModes: ModeConfig[], toolRequirements?: Record<string, boolean>, toolParams?: Record<string, any> )
-
Requirement Checking
- System capability verification
- Resource availability
- Permission validation
-
Parameter Validation
- Required parameter presence
- Parameter type checking
- Value validation
-
Initialization
- Tool name and parameters are validated
- Mode compatibility is checked
- Requirements are verified
-
Execution
const toolCall = { type: "tool_call", name: chunk.name, arguments: chunk.input, callId: chunk.callId }
-
Result Handling
- Success/failure determination
- Result formatting
- Error handling
-
Access Control
- File system restrictions
- Command execution limitations
- Network access controls
-
Validation Layers
- Tool-specific validation
- Mode-based restrictions
- System-level checks
Tools are made available based on the current mode:
- Code Mode: Full access to file system tools, code editing capabilities, command execution
- Ask Mode: Limited to reading tools, information gathering capabilities, no file system modifications
- Architect Mode: Design-focused tools, documentation capabilities, limited execution rights
- Custom Modes: Can be configured with specific tool access for specialized workflows
-
Process
- Current mode state preservation
- Tool availability updates
- Context switching
-
Impact on Tools
- Tool set changes
- Permission adjustments
- Context preservation
-
Efficiency
- Use the most specific tool for the task
- Avoid redundant tool calls
- Batch operations when possible
-
Security
- Validate inputs before tool calls
- Use minimum required permissions
- Follow security best practices
-
Error Handling
- Implement proper error checking
- Provide meaningful error messages
- Handle failures gracefully
-
Information Gathering
[ask_followup_question](/advanced-usage/available-tools/ask-followup-question) → [read_file](/advanced-usage/available-tools/read-file) → [search_files](/advanced-usage/available-tools/search-files) -
Code Modification
[read_file](/advanced-usage/available-tools/read-file) → [apply_diff](/advanced-usage/available-tools/apply-diff) → [attempt_completion](/advanced-usage/available-tools/attempt-completion) -
Task Management
[new_task](/advanced-usage/available-tools/new-task) → [switch_mode](/advanced-usage/available-tools/switch-mode) → [execute_command](/advanced-usage/available-tools/execute-command)
-
Tool-Specific Errors
- Parameter validation failures
- Execution errors
- Resource access issues
-
System Errors
- Permission denied
- Resource unavailable
- Network failures
-
Context Errors
- Invalid mode for tool
- Missing requirements
- State inconsistencies
-
Automatic Recovery
- Retry mechanisms
- Fallback options
- State restoration
-
User Intervention
- Error notifications
- Recovery suggestions
- Manual intervention options