Skip to main content

Tool Use Overview

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.

Core Concepts​

Tool Groups​

Tools are organized into logical groups based on their functionality:

CategoryPurposeToolsCommon Use
Read GroupFile system reading and searchingread_file, search_files, list_files, list_code_definition_namesCode exploration and analysis
Edit GroupFile system modificationsapply_diff, write_to_fileCode changes and file manipulation
Browser GroupWeb automationbrowser_actionWeb testing and interaction
Command GroupSystem command executionexecute_commandRunning scripts, building projects
MCP GroupExternal tool integrationuse_mcp_tool, access_mcp_resourceSpecialized functionality through external servers
Workflow GroupMode and task managementswitch_mode, new_task, ask_followup_question, attempt_completionContext switching and task organization

Always Available Tools​

Certain tools are accessible regardless of the current mode:

Available Tools​

Read Tools​

These tools help Roo understand your code and project:

Edit Tools​

These tools help Roo make changes to your code:

  • apply_diff - Makes precise, surgical changes to your code
  • write_to_file - Creates new files or completely rewrites existing ones

Browser Tools​

These tools help Roo interact with web applications:

Command Tools​

These tools help Roo execute commands:

MCP Tools​

These tools help Roo connect with external services:

Workflow Tools​

These tools help manage the conversation and task flow:

Tool Calling Mechanism​

When Tools Are Called​

Tools are invoked under specific conditions:

  1. 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

  2. Mode-Based Availability

    • Different modes enable different tool sets
    • Mode switches can trigger tool availability changes
    • Some tools are restricted to specific modes

  3. Context-Dependent Calls

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

    • System capability verification
    • Resource availability
    • Permission validation

  3. Parameter Validation

    • Required parameter presence
    • Parameter type checking
    • Value validation

Technical Implementation​

Tool Call Processing​

  1. Initialization

    • Tool name and parameters are validated
    • Mode compatibility is checked
    • Requirements are verified

  2. Execution

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

  3. Result Handling

    • Success/failure determination
    • Result formatting
    • Error handling

Security and Permissions​

  1. Access Control

    • File system restrictions
    • Command execution limitations
    • 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 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

Mode Switching​

  1. Process

    • Current mode state preservation
    • Tool availability updates
    • Context switching

  2. Impact on Tools

    • Tool set changes
    • Permission adjustments
    • Context preservation

Best Practices​

Tool Usage Guidelines​

  1. Efficiency

    • Use the most specific tool for the task
    • Avoid redundant tool calls
    • Batch operations when possible

  2. Security

    • Validate inputs before tool calls
    • Use minimum required permissions
    • 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](/features/tools/ask-followup-question) → [read_file](/features/tools/read-file) → [search_files](/features/tools/search-files)

  2. Code Modification

    [read_file](/features/tools/read-file) → [apply_diff](/features/tools/apply-diff) → [attempt_completion](/features/tools/attempt-completion)

  3. Task Management

    [new_task](/features/tools/new-task) → [switch_mode](/features/tools/switch-mode) → [execute_command](/features/tools/execute-command)

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 inconsistencies

Recovery Strategies​

  1. Automatic Recovery

    • Retry mechanisms
    • Fallback options
    • State restoration

  2. User Intervention

    • Error notifications
    • Recovery suggestions
    • Manual intervention options
Is this documentation incorrect or incomplete? Report an issue on GitHub