Skip to content

RubyLLM::Tool Base Class

All SharedTools extend RubyLLM::Tool, which provides a consistent DSL for defining tool parameters, descriptions, and execution logic. This guide covers the base class API and patterns.

Overview

RubyLLM::Tool is the foundation class from the RubyLLM gem that provides:

  • Parameter definition DSL
  • Tool description methods
  • Standardized execute interface
  • Integration with RubyLLM's tool system

Basic Tool Structure

Every tool follows this basic structure:

module SharedTools
  module Tools
    class MyTool < ::RubyLLM::Tool
      # 1. Define the model-visible tool name (snake_case)
      def self.tool_name = 'my'

      # 2. Describe what the tool does
      description <<~TEXT
        A brief description of what this tool does.

        Include usage examples and important notes.
      TEXT

      # 3. Define parameters
      parameters do
        string :action, description: "The action to perform"
        string :path,   description: "The file path (optional)", required: false
      end

      # 4. Implement initialization
      def initialize(driver: nil, logger: nil)
        @driver = driver
        @logger = logger || RubyLLM.logger
      end

      # 5. Implement execute method
      def execute(action:, path: nil)
        @logger&.info("Executing #{action} on #{path}")
        # Implementation here
      end
    end
  end
end

The Parameter DSL

Defining Parameters with parameters do ... end

The parameters block defines the parameters your tool accepts. Declare each one with its JSON type (string, integer, number, boolean, array, object). Parameters are required unless you pass required: false:

class BrowserTool < ::RubyLLM::Tool
  parameters do
    # Required parameter
    string :action, description: "The browser action to perform"

    # Optional parameter
    string :url, description: "The URL to visit (required for visit action)", required: false

    # Parameter with detailed description
    string :selector, description: <<~TEXT.strip, required: false
      A CSS selector to locate an element:

      * 'button[type="submit"]': selects a submit button
      * '.class-name': selects elements by class
      * '#id-name': selects an element by ID

      Required for click and text_field_set actions.
    TEXT

    # Parameter with examples
    integer :context_size, description: <<~TEXT.strip, required: false
      Number of parent elements to include (default: 2).

      Examples:
      - 1: Show only immediate parent
      - 2: Show parent and grandparent (default)
      - 3: Show three levels of context
    TEXT
  end
end

The ruby_llm 1.x param :name, desc: macro no longer exists; under ruby_llm 2.x it raises NoMethodError.

Parameter Description Best Practices

  1. Be Specific: Clearly state what the parameter does
  2. Include Examples: Show concrete usage examples
  3. Note Requirements: Indicate when the parameter is required
  4. Explain Defaults: Document default values
  5. List Options: For enum-like parameters, list all valid values

Example of a well-documented parameter:

string :action, description: <<~TEXT.strip
  The browser action to perform. Options:
  * `visit`: Navigate to a website (requires url)
  * `page_inspect`: Get page HTML or summary (optional: full_html)
  * `click`: Click an element (requires selector)
  * `text_field_set`: Enter text (requires selector and value)

  Example: action: "visit"
TEXT

The Description Method

The description method provides a comprehensive overview of your tool:

description <<~TEXT
  A tool for interacting with files and directories.

  This tool can:
  - Create, read, write, and delete files
  - Create, list, move, and delete directories
  - Replace text within files

  ## Important Notes

  - All paths are relative to the configured root directory
  - File operations require proper permissions
  - Use with caution as operations are destructive

  ## Example Usage

  Create and write to a file:
    {"action": "file_create", "path": "./demo.txt"}
    {"action": "file_write", "path": "./demo.txt", "text": "Hello"}

  Read a file:
    {"action": "file_read", "path": "./demo.txt"}

  Replace text in a file:
    {"action": "file_replace", "path": "./demo.txt",
     "old_text": "Hello", "new_text": "Hi"}
TEXT

Description Best Practices

  1. Start with Purpose: Begin with what the tool does
  2. List Capabilities: Bullet point the main features
  3. Include Warnings: Note any dangerous or destructive operations
  4. Provide Examples: Show concrete usage examples
  5. Document Actions: List all available actions with required parameters
  6. Add Context: Explain when to use this tool vs others

The Execute Method

The execute method is where your tool's logic lives:

Method Signature

def execute(action:, param1: nil, param2: default_value)
  # Implementation
end

Key points:

  • Use keyword arguments for all parameters
  • Provide default values for optional parameters
  • Match parameters defined with param DSL
  • Return consistent result types

Parameter Validation

Always validate required parameters:

def execute(action:, url: nil, selector: nil)
  case action
  when "visit"
    require_param!(:url, url)
    visit(url)
  when "click"
    require_param!(:selector, selector)
    click(selector)
  else
    raise ArgumentError, "Unknown action: #{action}"
  end
end

private

def require_param!(name, value)
  raise ArgumentError, "#{name} is required for this action" if value.nil?
end

Action Routing Pattern

Use action constants and case statements for routing:

module Action
  VISIT = "visit"
  CLICK = "click"
  SCREENSHOT = "screenshot"
end

ACTIONS = [Action::VISIT, Action::CLICK, Action::SCREENSHOT].freeze

def execute(action:, **params)
  case action.to_s.downcase
  when Action::VISIT
    handle_visit(**params)
  when Action::CLICK
    handle_click(**params)
  when Action::SCREENSHOT
    handle_screenshot(**params)
  else
    raise ArgumentError, "Unknown action: #{action}. " \
                        "Valid actions: #{ACTIONS.join(', ')}"
  end
end

Return Values

Be consistent with return values:

def execute(action:, path:)
  case action
  when "file_read"
    # Return string content
    File.read(path)

  when "file_write"
    File.write(path, text)
    # Return success message
    "Successfully wrote to #{path}"

  when "directory_list"
    # Return array of entries
    Dir.entries(path)

  when "database_query"
    # Return hash with status
    {
      status: :ok,
      result: db.execute(sql),
      rows_affected: db.changes
    }
  end
end

Initialization Patterns

Basic Initialization

class SimpleTool < ::RubyLLM::Tool
  def initialize(logger: nil)
    @logger = logger || RubyLLM.logger
  end
end

With Required Driver

class DatabaseTool < ::RubyLLM::Tool
  def initialize(driver:, logger: nil)
    raise ArgumentError, "driver is required" if driver.nil?
    @driver = driver
    @logger = logger || RubyLLM.logger
  end
end

With Optional Driver (Auto-detection)

class BrowserTool < ::RubyLLM::Tool
  def initialize(driver: nil, logger: nil)
    @logger = logger || RubyLLM.logger
    @driver = driver || default_driver
  end

  private

  def default_driver
    if defined?(Watir)
      Browser::WatirDriver.new(logger: @logger)
    else
      raise LoadError, "BrowserTool requires a driver or the watir gem"
    end
  end
end

With Configuration Options

class CustomTool < ::RubyLLM::Tool
  def initialize(root: Dir.pwd, timeout: 30, logger: nil)
    @root = root
    @timeout = timeout
    @logger = logger || RubyLLM.logger
  end
end

Logger Integration

All tools should support optional logging:

class MyTool < ::RubyLLM::Tool
  def initialize(logger: nil)
    @logger = logger || RubyLLM.logger
  end

  def execute(action:, path:)
    @logger&.info("Executing #{action} on #{path}")

    begin
      result = perform_action(action, path)
      @logger&.debug("Result: #{result.inspect}")
      result
    rescue => e
      @logger&.error("Failed: #{e.message}")
      raise
    end
  end
end

Logging Levels

Follow these conventions:

# INFO: High-level operations
@logger.info("BrowserTool: Navigating to #{url}")

# DEBUG: Detailed parameter values
@logger.debug("Parameters: #{params.inspect}")

# WARN: Recoverable issues
@logger.warn("Element not found, retrying...")

# ERROR: Failures and exceptions
@logger.error("Failed to execute: #{e.message}")

Tool Naming Convention

Override the tool_name class method to return a snake_case string. Do not override self.name: that is Ruby's Class#name, and replacing it garbles inspect output and constant-lookup error messages.

class BrowserTool < ::RubyLLM::Tool
  def self.tool_name = 'browser'
end

class MyCustomTool < ::RubyLLM::Tool
  def self.tool_name = 'my_custom'
end

Without an override, ruby_llm derives the name from the class name and drops a trailing _tool (MyCustomTool becomes my_custom). An override is used verbatim. SharedTools names follow the derived convention, with no _tool suffix.

This name is used by:

  • RubyLLM for tool registration
  • LLM for tool invocation
  • Logging and debugging
  • Error messages

Resource Cleanup

Tools that manage resources should provide cleanup methods:

class BrowserTool < ::RubyLLM::Tool
  def initialize(driver: nil)
    @driver = driver || Browser::WatirDriver.new
  end

  def cleanup!
    @driver&.close
    @driver = nil
  end

  # Alternative: Use Ruby's ObjectSpace finalizer
  def initialize(driver: nil)
    @driver = driver || Browser::WatirDriver.new

    ObjectSpace.define_finalizer(self, self.class.finalize(@driver))
  end

  def self.finalize(driver)
    proc { driver&.close }
  end
end

Usage:

browser = SharedTools::Tools::BrowserTool.new
begin
  browser.execute(action: "visit", url: "https://example.com")
ensure
  browser.cleanup!
end

Testing Tool Implementations

Unit Testing

Test the tool in isolation:

RSpec.describe SharedTools::Tools::MyTool do
  let(:logger) { instance_double(Logger) }
  let(:tool) { described_class.new(logger: logger) }

  describe "#execute" do
    it "handles valid action" do
      result = tool.execute(action: "test_action", path: "./test")
      expect(result).to eq("success")
    end

    it "raises error for invalid action" do
      expect {
        tool.execute(action: "invalid")
      }.to raise_error(ArgumentError, /Unknown action/)
    end

    it "requires path parameter" do
      expect {
        tool.execute(action: "test_action")
      }.to raise_error(ArgumentError, /path is required/)
    end

    it "logs execution" do
      expect(logger).to receive(:info).with(/Executing test_action/)
      tool.execute(action: "test_action", path: "./test")
    end
  end
end

Integration Testing

Test with real or mock drivers:

RSpec.describe SharedTools::Tools::BrowserTool do
  let(:driver) { MockBrowserDriver.new }
  let(:tool) { described_class.new(driver: driver) }

  it "navigates to URL using driver" do
    expect(driver).to receive(:goto).with(url: "https://test.com")
    tool.execute(action: "visit", url: "https://test.com")
  end
end

Common Patterns

Parameter Extraction

def execute(action:, **params)
  url = params[:url]
  selector = params[:selector]
  # Or use destructuring
  # url, selector = params.values_at(:url, :selector)

  perform_action(action, url, selector)
end

Default Values

def execute(action:, timeout: 30, retries: 3)
  options = {
    timeout: timeout,
    retries: retries
  }

  perform_with_options(action, options)
end

Boolean Flags

def execute(action:, full_html: false, summarize: true)
  if full_html
    get_full_html
  elsif summarize
    get_summary
  else
    get_basic_html
  end
end

Array Parameters

def execute(statements:)
  results = []

  statements.each do |statement|
    result = execute_single(statement)
    results << result
    break if result[:status] == :error
  end

  results
end

Advanced Patterns

Delegation to Sub-tools

class BrowserTool < ::RubyLLM::Tool
  def execute(action:, **params)
    case action
    when "visit"
      visit_tool.execute(**params)
    when "click"
      click_tool.execute(**params)
    end
  end

  private

  def visit_tool
    @visit_tool ||= Browser::VisitTool.new(driver: @driver, logger: @logger)
  end

  def click_tool
    @click_tool ||= Browser::ClickTool.new(driver: @driver, logger: @logger)
  end
end

Memoization

def execute(action:, path:)
  case action
  when "read"
    cached_read(path)
  end
end

private

def cached_read(path)
  @cache ||= {}
  @cache[path] ||= File.read(path)
end

Authorization Checks

def execute(action:, path:)
  return unless authorize!(action, path)

  perform_action(action, path)
end

private

def authorize!(action, path)
  return true if SharedTools.auto_execute

  SharedTools.execute?(
    tool: self.class.name,
    stuff: "#{action} on #{path}"
  )
end

Next Steps