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¶
- Be Specific: Clearly state what the parameter does
- Include Examples: Show concrete usage examples
- Note Requirements: Indicate when the parameter is required
- Explain Defaults: Document default values
- 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¶
- Start with Purpose: Begin with what the tool does
- List Capabilities: Bullet point the main features
- Include Warnings: Note any dangerous or destructive operations
- Provide Examples: Show concrete usage examples
- Document Actions: List all available actions with required parameters
- 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¶
Key points:
- Use keyword arguments for all parameters
- Provide default values for optional parameters
- Match parameters defined with
paramDSL - 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¶
- Learn about the Facade Pattern used by complex tools
- Understand Driver Interfaces for pluggable backends
- Review Example Tools for implementation patterns
- Read about Testing Strategies