module Riffer::Toolable

Riffer::Toolable provides the shared class-level DSL for anything that can present as a tool to an LLM — tools today, and subagents/workflows in the future.

Extend this module to make a class discoverable as a tool by LLM providers. Provides identifier, description, params, timeout, and JSON schema generation.

Instance-level execution concerns (call, call_with_validation, etc.) are NOT part of Toolable — those belong on Riffer::Tool.

class MyTool
  extend Riffer::Toolable

  description "Does something useful"

  params do
    required :input, String
  end
end

Constants

DEFAULT_TIMEOUT

Public Class Methods

all ()

Source

# File lib/riffer/toolable.rb, line 42
def self.all
  @extenders || []
end

Returns all classes that have extended Toolable.

extended (base)

Source

# File lib/riffer/toolable.rb, line 32
def self.extended(base)
  base.extend Riffer::Helpers::ClassNameConverter
  @extenders ||= []
  @extenders << base
end

Tracks all classes that extend Toolable.

Public Instance Methods

description (value = nil)

Source

# File lib/riffer/toolable.rb, line 50
def description(value = nil)
  return @description if value.nil?
  @description = value.to_s
end

Gets or sets the tool description.

identifier (value = nil)

Source

# File lib/riffer/toolable.rb, line 59
def identifier(value = nil)
  return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self)) if value.nil?
  @identifier = value.to_s
end

Gets or sets the tool identifier/name.

kind (value = nil)

Source

# File lib/riffer/toolable.rb, line 106
def kind(value = nil)
  return @kind || :tool if value.nil?
  @kind = value.to_sym
end

Returns the kind of toolable entity.

Defaults to :tool. Extensible to :agent, :workflow, etc.

name (value = nil)

Source

# File lib/riffer/toolable.rb, line 68
def name(value = nil)
  return identifier(value) unless value.nil?
  identifier
end

Alias for identifier — used by providers.

parameters_schema (strict: false)

Source

# File lib/riffer/toolable.rb, line 96
def parameters_schema(strict: false)
  @params_builder&.to_json_schema(strict: strict) || empty_schema
end

Returns the JSON Schema for the tool’s parameters.

params (&block)

Source

# File lib/riffer/toolable.rb, line 86
def params(&block)
  return @params_builder if block.nil?
  @params_builder = Riffer::Params.new
  @params_builder.instance_eval(&block)
end

Defines parameters using the Params DSL.

timeout (value = nil)

Source

# File lib/riffer/toolable.rb, line 77
def timeout(value = nil)
  return @timeout || DEFAULT_TIMEOUT if value.nil?
  @timeout = value.to_f
end

Gets or sets the tool timeout in seconds.

to_tool_schema (strict: false)

Source

# File lib/riffer/toolable.rb, line 115
def to_tool_schema(strict: false)
  {
    name: name,
    description: description,
    parameters_schema: parameters_schema(strict: strict)
  }
end

Returns a provider-agnostic tool schema hash.

validate_as_tool! ()

Source

# File lib/riffer/toolable.rb, line 129
def validate_as_tool!
  raise Riffer::ArgumentError, "#{self} must define a description" if description.nil? || description.to_s.strip.empty?
  raise Riffer::ArgumentError, "#{self} must have an identifier" if identifier.nil? || identifier.to_s.strip.empty?
  true
end

Validates that the minimum required metadata is present for LLM tool use.

Raises Riffer::ArgumentError if validation fails.