Tool Use (Agents)

Roflow's AI can autonomously perform actions in your development environment through a system of "tools" - structured commands that allow the AI to read files, search code, run tests, and more.

What Are Tools?

Tools are capabilities that extend the AI beyond just generating text. They allow the AI to:

Read files in your workspace
Search for code patterns
Run commands like Rojo sync or Wally install
Execute tests and show results
Generate assets like scripts or RemoteEvents
Apply diffs to modify your code

Agent Mode

When the AI uses tools, it operates in "agent mode" - autonomously breaking down tasks into steps and using tools to complete them.

How Tool Use Works

The Process

You make a request: "Add a RemoteEvent for player damage"
AI plans actions: Decides which tools to use
Dry-run preview: Shows what it will do
You approve: Review and confirm the actions
AI executes: Performs the approved actions
Results shown: You see what happened

Safety Features

All tool use includes safety measures:

✅ Dry-run first - Always shows what will happen
✅ Requires approval - Nothing executes without your OK
✅ Sandboxed - Limited to safe, reversible operations
✅ Logged - All actions are recorded
✅ Undoable - Changes can be reverted

User Control

You have complete control. The AI never performs destructive actions without your explicit approval.

Available Tools

File Operations

`readFile`

Reads the contents of a file:

AI: I need to read PlayerService.lua to understand the current structure.
Tool: readFile(src/services/PlayerService.lua)

`searchFiles`

Searches for patterns across your codebase:

AI: Let me find all RemoteEvent usages.
Tool: searchFiles(pattern: "RemoteEvent", include: "*.lua")

`applyDiff`

Applies code changes using the diff-apply workflow:

AI: I'll add type checking to this function.
Tool: applyDiff(file: "init.lua", changes: [...])

Roblox Toolchain

`rojoSync`

Syncs your project to Roblox Studio:

AI: I'll sync the project to Studio for testing.
Tool: rojoSync()
Result: ✓ Synced successfully to Roblox Studio

`wallyInstall`

Installs Wally dependencies:

AI: Installing the Promise package.
Tool: wallyInstall(package: "evaera/promise")
Result: ✓ Installed Promise@4.0.0

`seleneLint`

Runs Selene linter:

AI: Let me check for linting issues.
Tool: seleneLint()
Result: Found 3 warnings in 2 files

`testEZ`

Runs TestEZ unit tests:

AI: Running tests to verify the changes.
Tool: testEZ(tests: "src/**/*.spec.lua")
Result: ✓ 15 tests passed, 0 failed

Asset Generation

`generateRemoteEvent`

Creates a new RemoteEvent:

AI: Creating a RemoteEvent for player damage.
Tool: generateRemoteEvent(name: "PlayerDamaged", location: "ReplicatedStorage/Events")

`generateScript`

Scaffolds a new script:

AI: Creating a new ModuleScript for the inventory system.
Tool: generateScript(
  type: "ModuleScript",
  name: "InventoryManager",
  framework: "Knit"
)

Code Analysis

`codeSearch`

Semantic code search using ripgrep:

AI: Finding all occurrences of deprecated APIs.
Tool: codeSearch(query: "game.Players.LocalPlayer", context: 3)

Tool Use in Action

Example 1: Adding a Feature

Your Request:

"Add a cooldown system to the weapon script"

AI Agent Process:

Step 1: Read current weapon script
  Tool: readFile("src/weapons/Sword.lua")

Step 2: Plan implementation
  [AI analyzes code and plans changes]

Step 3: Apply changes with cooldown logic
  Tool: applyDiff("src/weapons/Sword.lua", [...])

Step 4: Sync to Studio for testing
  Tool: rojoSync()

✓ Cooldown system added successfully!

Example 2: Debugging

Your Request:

"Why is the player spawning with 0 health?"

AI Agent Process:

Step 1: Search for player spawn code
  Tool: searchFiles(pattern: "Player.Character")

Step 2: Read identified files
  Tool: readFile("src/services/PlayerService.lua")
  Tool: readFile("src/handlers/SpawnHandler.lua")

Step 3: Analyze and explain
  [AI identifies the issue in the code]

Found the issue: Health is set before the Character loads.
Let me fix this with CharacterAdded event.

Step 4: Apply fix
  Tool: applyDiff("src/handlers/SpawnHandler.lua", [...])

✓ Fixed player spawn health issue!

Example 3: Refactoring

Your Request:

"Refactor PlayerStats to use attributes instead of values"

AI Agent Process:

Step 1: Read current implementation
  Tool: readFile("src/modules/PlayerStats.lua")

Step 2: Search for all usages
  Tool: searchFiles(pattern: "PlayerStats:GetStat")

Step 3: Update implementation
  Tool: applyDiff("src/modules/PlayerStats.lua", [...])

Step 4: Update all call sites
  Tool: applyDiff("src/controllers/UIController.lua", [...])
  Tool: applyDiff("src/systems/CombatSystem.lua", [...])

Step 5: Run tests
  Tool: testEZ(tests: "**/*.spec.lua")

✓ Refactored to use attributes. All 23 tests pass!

Reviewing Tool Actions

Dry-Run Preview

Before executing, the AI shows you the plan:

⚙️ Proposed Actions:

1. Read src/services/DataService.lua
2. Search for "DataStore2" references
3. Apply changes to implement autosave
4. Run tests to verify functionality

Do you want to proceed? [Yes] [No] [Modify]

Your Options:

Yes - Proceed with all actions
No - Cancel and refine your request
Modify - Remove or adjust specific actions

Step-by-Step Execution

You can execute tools one at a time:

AI shows next tool
You approve or skip
Tool executes
Results shown
AI proceeds to next tool

Enable in settings:

{
  "roflow.tools.stepByStep": true
}

Tool Permissions

Default Permissions

By default, all Roflow tools are allowed. They are designed to be safe and reversible.

Restricting Tools

To disable specific tools:

{
  "roflow.tools.disabled": [
    "wallyInstall",  // Don't allow automatic package installation
    "rojoSync"       // Don't allow automatic syncing
  ]
}

Dangerous Operations

Some tools are inherently safe:

✅ Reading files (read-only)
✅ Searching code (read-only)
✅ Linting (read-only)

Others require more caution:

⚠️ Applying diffs (modifies code)
⚠️ Installing packages (modifies dependencies)
⚠️ Running commands (executes code)

All potentially destructive tools always require approval before execution.

Tool Use Settings

Automatic Approval

For trusted operations, enable auto-approval:

{
  "roflow.tools.autoApprove": {
    "readFile": true,
    "searchFiles": true,
    "seleneLint": true,
    "testEZ": false,
    "applyDiff": false
  }
}

Use Caution

Auto-approval for code changes (applyDiff) is not recommended unless you're actively monitoring the AI's actions.

Tool Timeout

Set maximum execution time:

{
  "roflow.tools.timeout": 30000  // 30 seconds
}

Concurrency

Allow multiple tools to run in parallel:

{
  "roflow.tools.parallel": true,
  "roflow.tools.maxConcurrent": 3
}

Understanding Tool Output

Success

✓ Tool: rojoSync()
  Result: Successfully synced to Roblox Studio
  Duration: 1.2s

Failure

✗ Tool: wallyInstall(package: "invalid/package")
  Error: Package not found in registry
  Suggestion: Check package name spelling

Partial Success

⚠ Tool: testEZ()
  Result: 18 passed, 2 failed
  Details: See test output below

  Failed tests:
    - InventorySystem.spec: "should stack items"
    - PlayerStats.spec: "should save on leave"

Tool Logs

Viewing Logs

Access tool execution logs:

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Type "Show AI Tool Logs"
View chronological log of all tool executions

Log Contents

Each log entry includes:

Timestamp
Tool name and parameters
Execution duration
Result or error
AI's reasoning for using the tool

Export Logs

Export logs for debugging or sharing:

File > Export > AI Tool Logs

Best Practices

Effective Tool Use

✓ Do:

Let the AI use tools to explore your codebase
Review tool plans before approving
Use tools iteratively (read → analyze → modify)
Keep version control active

✗ Don't:

Auto-approve all tools without understanding them
Skip reviewing changes from applyDiff
Ignore tool errors
Disable safety features

Combining Tools

Tools work best when combined:

Read files → Understand code → Search patterns → Apply changes → Test

The AI will chain tools naturally to complete complex tasks.

Troubleshooting

Tool Execution Failed

Check:

File permissions
Required binaries installed (Rojo, Wally, etc.)
Valid project structure
Network connection (for remote tools)

Tool Stuck/Hanging

If a tool doesn't complete:

Wait for timeout (default 30s)
Cancel with Esc key
Check logs for error details
Try running the command manually to diagnose

Unexpected Results

If tool results are unexpected:

Review the tool parameters in the log
Check if the AI misunderstood your request
Provide more specific context in your next message
Manually verify the tool's actions

Advanced Usage

Custom Tools

Roflow supports custom tool definitions. See Advanced > Custom Tools for details.

Tool Chaining

Request complex multi-step operations:

"Search for all Player-related scripts,
read them, identify data race conditions,
and fix them with proper locks"

The AI will automatically chain the necessary tools.

Debugging with Tools

Use tools to help debug:

"Use tools to find why the shop isn't working"

The AI will systematically use read and search tools to diagnose.

Next Steps

Prompt Guide - Write effective requests
Advanced Features - Learn about code actions
Troubleshooting - Solve AI-related issues

PreviousDiff-Apply Workflow

NextBest Practices