### Minimal ToolForge Example

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

A complete, minimal example demonstrating how to define a tool using ToolForge. This tool echoes its input.

```ruby
require 'tool_forge'

tool = ToolForge.define(:echo) do
  description 'Echoes input'
  param :text, type: :string
  execute { |text:| text }
end
```

--------------------------------

### Basic Example: Complete Minimal Example

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

A self-contained, minimal tool definition showcasing all essential components.

```ruby
class MinimalTool < ToolForge::Tool
  description("A minimal tool.")
  param(:message, type: "string")

  execute do |message|
    message || "Default message."
  end
end
```

--------------------------------

### Example: Using Instance Helpers for Text Formatting

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-definition.md

This example demonstrates defining and using instance helpers `format_text` and `add_prefix` within a `ToolForge.define` block. The `format_text` helper handles different text transformations, while `add_prefix` adds a standard prefix.

```ruby
tool = ToolForge.define(:text_processor) do
  param :text, type: :string
  param :format, type: :string, default: 'uppercase'

  helper(:format_text) do |text, format|
    case format
    when 'uppercase' then text.upcase
    when 'lowercase' then text.downcase
    when 'title' then text.split.map(&:capitalize).join(' ')
    else text
    end
  end

  helper(:add_prefix) do |text|
    "PROCESSED: #{text}"
  end

  execute do |text:, format:|
    formatted = format_text(text, format)
    add_prefix(formatted)
  end
end
```

--------------------------------

### Install Bundled Gems

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/configuration.md

Installs all gems specified in the Gemfile, including ToolForge if added.

```bash
bundle install
```

--------------------------------

### Usage Example: Simple Tool Invocation

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Demonstrates how to instantiate and execute a simple tool.

```ruby
tool = MyTool.new(input: "test")
result = tool.execute
puts result # Output: Received: test
```

--------------------------------

### Install ToolForge Gem

Source: https://github.com/afstanton/tool_forge/blob/main/README.md

Install the ToolForge gem using Bundler or directly via gem install.

```bash
bundle add tool_forge
```

```bash
gem install tool_forge
```

--------------------------------

### Basic Example: Hello World

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

A minimal 'Hello World' tool demonstrating basic description, parameter, and execution.

```ruby
class HelloWorldTool < ToolForge::Tool
  description("A tool that greets the user.")
  param(:name, type: "string", default: "World")

  execute do |name|
    "Hello, #{name}!"
  end
end
```

--------------------------------

### ToolForge Installation

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/00-START-HERE.md

Install the ToolForge gem for basic functionality. Optionally include ruby_llm and mcp gems if you plan to use their respective features.

```bash
# Basic installation
gem install tool_forge

# In your Gemfile
gem 'tool_forge'
gem 'ruby_llm'   # if you'll use RubyLLM
gem 'mcp'        # if you'll use MCP
```

--------------------------------

### Setup ToolForge with MCP Integration

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/configuration.md

Configures ToolForge for use with the Model Context Protocol (MCP) SDK. Requires both gems to be installed and required.

```ruby
# Gemfile
gem 'tool_forge'
gem 'mcp'

# In your code
require 'mcp'
require 'tool_forge'

tool = ToolForge.define(:my_tool) do
  # ... tool definition
end

mcp_tool = tool.to_mcp_tool
```

--------------------------------

### Setup ToolForge with RubyLLM Integration

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/configuration.md

Configures ToolForge for use with the RubyLLM framework. Requires both gems to be installed and required.

```ruby
# Gemfile
gem 'tool_forge'
gem 'ruby_llm'

# In your code
require 'ruby_llm'
require 'tool_forge'

tool = ToolForge.define(:my_tool) do
  # ... tool definition
end

ruby_llm_tool = tool.to_ruby_llm_tool
```

--------------------------------

### Framework Example: RubyLLM Integration

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Shows how to integrate a Tool Forge tool with the RubyLLM framework.

```ruby
class RubyLLMIntegrationTool < ToolForge::Tool
  description("A tool for RubyLLM.")
  param(:query, type: "string", required: true)

  execute do |query|
    # Logic to interact with RubyLLM
    "Processed query: #{query}"
  end

  def to_ruby_llm_tool
    # Conversion logic specific to RubyLLM
    { name: self.class.name.demodulize, description: description, parameters: parameters.to_h }
  end
end
```

--------------------------------

### ToolForge Module Setup with Zeitwerk

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-forge-module.md

Illustrates the Zeitwerk autoloader configuration for the ToolForge gem, including ignoring the version file and automatic setup.

```ruby
# The loader is instantiated as a gem loader via `Zeitwerk::Loader.for_gem`
# The version file is explicitly ignored to prevent conflicts
# The loader is automatically set up when the module is loaded
```

--------------------------------

### Example: Using Class Helpers for Validation and Tar Operations

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-definition.md

This example shows how to define and use class helpers `validate_container` and `add_to_tar` for a Docker-related tool. `validate_container` checks the format of a container ID, and `add_to_tar` simulates adding a file to a tar archive.

```ruby
tool = ToolForge.define(:docker_copy) do
  param :container_id, type: :string
  param :source_path, type: :string
  param :dest_path, type: :string

  class_helper(:validate_container) do |container_id|
    container_id.match?(/^[a-f0-9]{12}$/)
  end

  class_helper(:add_to_tar) do |file_path, tar_path|
    "Added #{file_path} to tar archive as #{tar_path}"
  end

  execute do |container_id:, source_path:, dest_path:|
    return "Invalid container ID" unless self.class.validate_container(container_id)
    tar_result = self.class.add_to_tar(source_path, dest_path)
    "Copied to #{container_id}:#{dest_path} - #{tar_result}"
  end
end
```

--------------------------------

### Usage Example: Tool with Required Parameters

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Illustrates calling a tool that requires specific parameters, demonstrating error if missing.

```ruby
# Assuming MyTool requires :input
# tool = MyTool.new # This would raise an error if :input is required and not provided
tool = MyTool.new(input: "value")
puts tool.execute
```

--------------------------------

### ToolDefinition Initialization and Usage Example

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-definition.md

Demonstrates how to create and configure a ToolDefinition instance using its DSL. Shows setting a description, defining a parameter, and specifying the execution logic.

```ruby
tool = ToolForge::ToolDefinition.new(:my_tool) do
  description 'A sample tool'
  param :input, type: :string
  execute { |input:| "Processed: #{input}" }
end

puts tool.name           #=> :my_tool
puts tool.description   #=> 'A sample tool'
puts tool.params.length #=> 1
```

--------------------------------

### Basic Example: Echo with Repetition

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

An example tool that echoes input text a specified number of times.

```ruby
class EchoTool < ToolForge::Tool
  description("Echoes the input text multiple times.")
  param(:text, type: "string", required: true)
  param(:times, type: "integer", default: 1)

  execute do |text, times|
    text * times
  end
end
```

--------------------------------

### RubyLLM Tool Usage Example

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/types.md

Demonstrates how to define a tool using ToolForge, convert it to a RubyLLM compatible class, instantiate it, and execute it with parameters and context.

```ruby
require 'ruby_llm'
require 'tool_forge'

tool_def = ToolForge.define(:greet) do
  description 'Greets a user'
  param :name, type: :string
  
  execute do |name:, context: nil|
    "Hello, #{name}!"
  end
end

ruby_llm_tool = tool_def.to_ruby_llm_tool
instance = ruby_llm_tool.new

result = instance.execute(name: 'Alice', context: { user_id: 123 })
#=> "Hello, Alice!"
```

--------------------------------

### Install Tool Forge Gem

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/INDEX.md

Use this command to install the Tool Forge gem globally on your system.

```bash
gem install tool_forge
```

--------------------------------

### Usage Example: Tool with Default Parameters

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Shows invoking a tool where some parameters have default values.

```ruby
tool = MinimalTool.new # Uses default message
result = tool.execute
puts result # Output: Default message.
```

--------------------------------

### Advanced Example: Docker Operations Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

An advanced tool for interacting with Docker, such as running containers or managing images.

```ruby
class DockerTool < ToolForge::Tool
  description("Performs Docker operations.")
  param(:command, type: "string", required: true)
  param(:args, type: "array", default: [])

  execute do |command, args|
    # System call to execute Docker command
    `docker #{command} #{args.join(' ')}`
  end
end
```

--------------------------------

### Framework Example: MCP Integration with Response Formatting

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Demonstrates integrating a Tool Forge tool with the MCP framework, specifying response formatting.

```ruby
class MCPIntegrationTool < ToolForge::Tool
  description("A tool for MCP.")
  param(:input, type: "string", required: true)

  execute do |input|
    # Logic to interact with MCP
    { result: "MCP response for: #{input}" }
  end

  def to_mcp_tool(response_format: :json)
    # Conversion logic specific to MCP
    { name: self.class.name.demodulize, description: description, parameters: parameters.to_h, response_format: response_format }
  end
end
```

--------------------------------

### MCP Tool Usage Example

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/types.md

Illustrates defining a tool with ToolForge, converting it to an MCP compatible class, and calling it with server context and parameters. The response is automatically formatted by the MCP framework.

```ruby
require 'mcp'
require 'tool_forge'

tool_def = ToolForge.define(:greet) do
  description 'Greets a user'
  param :name, type: :string
  
  execute do |name:|
    "Hello, #{name}!"
  end
end

mcp_tool = tool_def.to_mcp_tool

response = mcp_tool.call(server_context: nil, name: 'Bob')
#=> MCP::Tool::Response instance with formatted content
```

--------------------------------

### Tool Definition Example

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/types.md

An example of defining a tool with parameters, including types and descriptions. This definition is used to generate the input schema.

```ruby
tool = ToolForge.define(:example) do
  param :name, type: :string, description: 'User name'
  param :age, type: :integer, description: 'User age'
  param :tags, type: :array, required: false
end
```

--------------------------------

### Multi-Framework Example: Single Definition

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Illustrates defining a single tool that can be converted and used with multiple frameworks like RubyLLM and MCP.

```ruby
class MultiFrameworkTool < ToolForge::Tool
  description("A tool usable with multiple frameworks.")
  param(:message, type: "string", required: true)

  execute do |message|
    "Message: #{message}"
  end

  def to_ruby_llm_tool
    { name: self.class.name.demodulize, description: description, parameters: parameters.to_h }
  end

  def to_mcp_tool(response_format: :json)
    { name: self.class.name.demodulize, description: description, parameters: parameters.to_h, response_format: response_format }
  end
end
```

--------------------------------

### Define a Simple 'Hello World' Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/examples.md

This snippet shows the most basic ToolForge tool definition. It includes a description, a required string parameter, and an execution block that returns a greeting. Use this as a starting point for creating new tools.

```ruby
require 'tool_forge'

tool = ToolForge.define(:hello) do
  description 'Says hello'
  
  param :name, type: :string, description: 'Name to greet'
  
  execute do |name מד:|
    "Hello, #{name}!"
  end
end

# Test it
result = tool.execute_block.call(name: 'World')
puts result  # => "Hello, World!"
```

--------------------------------

### Module Setup: Zeitwerk Integration

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Configuration for integrating Tool Forge with Zeitwerk for efficient code autoloading.

```ruby
require 'zeitwerk'
loader = Zeitwerk::Loader.new
loader.push_dir("lib")
loader.setup
```

--------------------------------

### Error Handling Example

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Demonstrates comprehensive error handling within a tool, including custom error classes.

```ruby
class ErrorHandlingTool < ToolForge::Tool
  description("Demonstrates error handling.")
  param(:value, type: "integer", required: true)

  execute do |value|
    if value < 0
      raise ToolForge::Error.new("Value cannot be negative.")
    elsif value == 0
      raise ToolForge::LoadError.new("Value cannot be zero for this operation.")
    else
      "Processed value: #{value}"
    end
  end
end
```

--------------------------------

### Advanced Example: Database Query Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

An advanced tool for executing database queries, abstracting database interactions.

```ruby
class DatabaseQueryTool < ToolForge::Tool
  description("Executes database queries.")
  param(:query, type: "string", required: true)
  param(:db_connection, type: "object", required: true)

  execute do |query, db_connection|
    db_connection.execute(query)
  end
end
```

--------------------------------

### Define Tool with Instance and Class Helpers

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/types.md

Example of defining a tool using `ToolForge.define` and adding both instance and class helper methods. Accessing these methods demonstrates their retrieval from the `helper_methods` hash.

```ruby
tool = ToolForge.define(:example) do
  helper(:format_output) do |data|
    "OUTPUT: #{data.inspect}"
  end
  
  class_helper(:validate_input) do |input|
    !input.nil? && !input.empty?
  end
end

# Access helper methods
tool.helper_methods[:instance][:format_output]
#=> #<Proc:0x00007f...>

tool.helper_methods[:class][:validate_input]
#=> #<Proc:0x00007f...>
```

--------------------------------

### Testing Example: Unit Testing Tools

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Shows how to write unit tests for Tool Forge tools, verifying their behavior and outputs.

```ruby
require 'rspec'
require_relative '../lib/tool_forge'

describe HelloWorldTool do
  it "greets the user with a default name" do
    tool = HelloWorldTool.new
    expect(tool.execute).to eq("Hello, World!")
  end

  it "greets the user with a provided name" do
    tool = HelloWorldTool.new(name: "Alice")
    expect(tool.execute).to eq("Hello, Alice!")
  end
end
```

--------------------------------

### ToolForge Parameter Definition Usage

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/types.md

Example of defining a tool with various parameter types and accessing their definitions.

```ruby
tool = ToolForge.define(:example) do
  param :input_text, type: :string, 
        description: 'The text to process',
        required: true
  
  param :max_length, type: :integer,
        description: 'Maximum output length',
        required: false,
        default: 100
  
  param :preserve_case, type: :boolean,
        description: 'Preserve original case',
        required: false,
        default: true
end

# Access parameter definitions
tool.params.each do |param|
  puts "#{param[:name]} (#{param[:type]}): #{param[:description]}"
end
```

--------------------------------

### Basic Example: Text Transformation

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

A tool that transforms input text, for instance, by converting it to uppercase.

```ruby
class TextTransformTool < ToolForge::Tool
  description("Transforms the input text.")
  param(:input_text, type: "string", required: true)

  execute do |input_text|
    input_text.upcase
  end
end
```

--------------------------------

### Advanced Example: API Client Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

An advanced tool that acts as a client for an external API, making requests and handling responses.

```ruby
require 'net/http'
require 'uri'

class ApiClientTool < ToolForge::Tool
  description("Interacts with an external API.")
  param(:api_endpoint, type: "string", required: true)
  param(:method, type: "string", default: "GET")
  param(:payload, type: "object")

  execute do |api_endpoint, method, payload|
    uri = URI.parse(api_endpoint)
    http = Net::HTTP.new(uri.host, uri.port)
    request = Object.const_get("Net::HTTP::" + method.capitalize).new(uri.request_uri)
    request.body = payload.to_json if payload
    response = http.request(request)
    response.body
  end
end
```

--------------------------------

### Helper Example: Instance Helper for Text Processing

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Demonstrates using an instance helper method to process text within the execute block.

```ruby
class TextProcessorTool < ToolForge::Tool
  description("Processes text using an instance helper.")
  param(:text, type: "string", required: true)

  helper(:reverse_text) { |t| t.reverse }

  execute do |text|
    reverse_text(text)
  end
end
```

--------------------------------

### Define and Use a Tool with RubyLLM and MCP

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/00-START-HERE.md

Define a tool using ToolForge's DSL and then convert it for use with RubyLLM and MCP frameworks. Ensure you have the respective gems installed.

```ruby
require 'tool_forge'

# Define a tool
tool = ToolForge.define(:greet) do
  description 'Greets a user'
  param :name, type: :string
  execute { |name:| "Hello, #{name}!" }
end

# Use with RubyLLM
require 'ruby_llm'
ruby_llm_tool = tool.to_ruby_llm_tool
instance = ruby_llm_tool.new
instance.execute(name: 'Alice')  # => "Hello, Alice!"

# Use with MCP
require 'mcp'
mcp_tool = tool.to_mcp_tool
mcp_tool.call(server_context: nil, name: 'Bob')  # => MCP response
```

--------------------------------

### Define Instance Helper Method

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/INDEX.md

Create instance helper methods within a tool definition that can be called directly within the `execute` block. This example defines a `format` helper.

```ruby
helper(:format) { |text| text.upcase }
execute { |input:| format(input) }
```

--------------------------------

### Error Handling: ToolForge::LoadError

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Example of raising ToolForge::LoadError for problems during tool loading or definition.

```ruby
raise ToolForge::LoadError, "Failed to load tool configuration."
```

--------------------------------

### Advanced Example: File Processing Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

An advanced tool designed to process files, potentially reading, writing, or transforming content.

```ruby
class FileProcessorTool < ToolForge::Tool
  description("Processes a given file.")
  param(:file_path, type: "string", required: true)
  param(:operation, type: "string", default: "read")

  execute do |file_path, operation|
    case operation
    when "read"
      File.read(file_path)
    when "write"
      File.write(file_path, "Content written by tool.")
    else
      "Unsupported operation."
    end
  end
end
```

--------------------------------

### Helper Example: Class Helper for Data Validation

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Illustrates using a class helper method for data validation before execution.

```ruby
class DataValidatorTool < ToolForge::Tool
  description("Validates data using a class helper.")
  param(:data, type: "object", required: true)

  class_helper(:is_valid_data?) { |d| d.is_a?(Hash) && d.key?(:id) }

  execute do |data|
    if self.class.is_valid_data?(data)
      "Data is valid."
    else
      "Invalid data."
    end
  end
end
```

--------------------------------

### Define an 'Echo' Tool with Optional Repetition

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/examples.md

This example defines a tool that echoes text a specified number of times. It demonstrates the use of an optional integer parameter with a default value. Useful for repetitive output tasks.

```ruby
tool = ToolForge.define(:echo) do
  description 'Echoes text multiple times'
  
  param :text, type: :string, description: 'Text to echo'
  param :times, type: :integer, required: false, default: 1, description: 'Number of times'
  
  execute do |text:, times מד:|
    (0...times).map { "#{_1 + 1}: #{text}" }.join("\n")
  end
end

result = tool.execute_block.call(text: 'Hello', times: 3)
puts result
# => 1: Hello
#    2: Hello
#    3: Hello
```

--------------------------------

### Enable Eager Loading with Zeitwerk

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/configuration.md

Use this snippet to eagerly load all ToolForge code, which can be beneficial for performance in certain application setups.

```ruby
require 'tool_forge'

# Eager load all ToolForge code
ToolForge.loader.eager_load
```

--------------------------------

### Define Tool with Complex Parameter Types

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Define a tool that accepts array and object types for its parameters. This example shows how to use `:array` and `:object` types and how to integrate with RubyLLM.

```ruby
tool_def = ToolForge.define(:data_analyzer) do
  description 'Analyzes structured data'
  
  param :records, type: :array, description: 'Array of record objects'
  param :config, type: :object, description: 'Configuration settings'
  
  helper(:analyze_records) do |records|
    {
      total: records.length,
      types: records.map { |r| r['type'] }.uniq
    }
  end
  
  execute do |records:, config:|
    filter_type = config['filter_type']
    filtered = filter_type ? records.select { |r| r['type'] == filter_type } : records
    
    {
      input_count: records.length,
      filtered_count: filtered.length,
      analysis: analyze_records(filtered)
    }
  end
end

# Use with RubyLLM
ruby_llm_class = tool_def.to_ruby_llm_tool
instance = ruby_llm_class.new
result = instance.execute(
  records: [
    { type: 'log', message: 'Test 1' },
    { type: 'event', message: 'Test 2' }
  ],
  config: { filter_type: 'log' }
)
```

--------------------------------

### Get ToolForge Version

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Access the ToolForge::VERSION constant to retrieve the currently installed version of the library.

```ruby
ToolForge::VERSION  # => '0.2.2'
```

--------------------------------

### Generated Input Schema from Tool Definition

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/types.md

The resulting input schema object generated from the example tool definition. It maps parameter names to their types and descriptions, and lists required parameters.

```ruby
{
  properties: {
    "name" => { type: "string", description: "User name" },
    "age" => { type: "integer", description: "User age" },
    "tags" => { type: "array" }
  },
  required: ["name", "age"]
}
```

--------------------------------

### Define Tool with Conditional Behavior

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Define a tool that exhibits conditional behavior based on an operation parameter. This example demonstrates using helpers for different operations and handling optional parameters.

```ruby
tool_def = ToolForge.define(:conditional_processor) do
  description 'Processes data conditionally'
  
  param :input, type: :string
  param :operation, type: :string, description: 'Operation: analyze, transform, validate'
  param :options, type: :object, required: false
  
  helper(:analyze) do |input|
    { type: 'analysis', length: input.length, words: input.split.length }
  end
  
  helper(:transform) do |input, options|
    case options&.dig('style')
    when 'uppercase' then input.upcase
    when 'reverse' then input.reverse
    else input
    end
  end
  
  helper(:validate) do |input|
    input.length > 0 && input.length < 1000
  end
  
  execute do |input:, operation:, options: nil|
    case operation
    when 'analyze' then analyze(input)
    when 'transform' then transform(input, options)
    when 'validate' then { valid: validate(input) }
    else { error: "Unknown operation: #{operation}" }
    end
  end
end
```

--------------------------------

### Defining and Testing a ToolForge Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Define a simple tool with a string parameter and execute it. Demonstrates basic tool definition and direct execution testing. Also shows conversion to RubyLLM and MCP tool formats.

```ruby
require 'tool_forge'

tool_def = ToolForge.define(:test_tool) do
  description 'Test tool'
  param :input, type: :string
  execute { |input:| "Output: #{input}" }
end

# Test execution
result = tool_def.execute_block.call(input: 'test')
puts result  # => "Output: test"

# Test RubyLLM conversion
require 'ruby_llm'
ruby_llm_class = tool_def.to_ruby_llm_tool
instance = ruby_llm_class.new
puts instance.execute(input: 'llm')  # => "Output: llm"

# Test MCP conversion
require 'mcp'
mcp_class = tool_def.to_mcp_tool
response = mcp_class.call(server_context: nil, input: 'mcp')
puts response  # => MCP::Tool::Response
```

--------------------------------

### ToolDefinition DSL - description

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Sets or gets the description for a ToolDefinition.

```APIDOC
## description(text = nil)

### Description
Sets or gets the description for a ToolDefinition.

### Method
`ToolDefinition#description`

### Parameters
- **text** (String) - Optional - The description text to set.
```

--------------------------------

### Define and Convert ToolForge Tools

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Demonstrates how to define a tool and then convert it to different formats like Ruby LLM or MCP. It's recommended to save the definition for multiple conversions.

```ruby
# Define and immediately convert
tool = ToolForge.define(:my_tool) do
  # ...
end.to_ruby_llm_tool  # Returns tool class, not ToolDefinition

# Better: save definition for both conversions
tool_def = ToolForge.define(:my_tool) do
  # ...
end

ruby_llm_tool = tool_def.to_ruby_llm_tool
mcp_tool = tool_def.to_mcp_tool
```

--------------------------------

### Get Version

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Retrieves the current version of the ToolForge library.

```APIDOC
## Get Version

### Description
Retrieves the current version of the ToolForge library.

### Method
ToolForge::VERSION

### Return
String representing the current version.
```

--------------------------------

### Error Handling: ToolForge::Error

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Example of raising the base ToolForge::Error for general issues.

```ruby
raise ToolForge::Error, "Something went wrong in Tool Forge."
```

--------------------------------

### Define Tool Description

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-definition.md

Sets or gets the tool's description. This is used by converters for context.

```ruby
def description(text = nil)
  if text
    @description = text
  else
    @description
  end
end
```

```ruby
tool = ToolForge.define(:file_reader) do
  description 'Reads and processes files'
end

# Get description
puts tool.description #=> 'Reads and processes files'
```

--------------------------------

### Define and Use a Tool with ToolForge

Source: https://github.com/afstanton/tool_forge/blob/main/README.md

Define a tool with parameters and an execution block, then convert it to RubyLLM format and execute it. Ensure the 'tool_forge' gem is required.

```ruby
require 'tool_forge'

# Define a tool
tool = ToolForge.define(:greet_user) do
  description 'Greets a user with a personalized message'

  param :name, type: :string, description: 'User name'
  param :greeting, type: :string, description: 'Greeting style',
        required: false, default: 'Hello'

  execute do |name:, greeting מד:|
    "#{greeting}, #{name}! Welcome to ToolForge!"
  end
end

# Convert to RubyLLM format
ruby_llm_tool = tool.to_ruby_llm_tool
instance = ruby_llm_tool.new
result = instance.execute(name: 'Alice')
#=> "Hello, Alice! Welcome to ToolForge!"

# Convert to MCP format
mcp_tool = tool.to_mcp_tool
result = mcp_tool.call(server_context: nil, name: 'Bob')
#=> Returns MCP::Tool::Response object
```

--------------------------------

### Create a Tool Definition

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Use ToolForge.define to create a new tool, specifying its name, description, parameters, and execution logic. This returns a ToolDefinition instance.

```ruby
require 'tool_forge'

tool = ToolForge.define(:tool_name) do
  description 'What this tool does'
  param :input, type: :string
  execute { |input:| input }
end
```

--------------------------------

### Register ToolForge Tool with RubyLLM Client

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Defines a 'greet' tool and converts it to RubyLLM format before adding it to a RubyLLM client. This makes the tool available for use by the LLM.

```ruby
require 'ruby_llm'
require 'tool_forge'

# Define tools
greeting_tool = ToolForge.define(:greet) do
  description 'Greets a person'
  param :name, type: :string
  param :formal, type: :boolean, required: false, default: false
  
  execute do |name:, formal מד:| 
    formal ? "Good day, #{name}." : "Hey #{name}!"
  end
end

# Convert and register with RubyLLM
client = RubyLLM::Client.new
client.add_tool(greeting_tool.to_ruby_llm_tool)

# The tool is now available to the LLM
```

--------------------------------

### Define a Basic Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/INDEX.md

Define a tool using the `ToolForge.define` API with a configuration block. This sets up the tool's name, description, parameters, and execution logic.

```ruby
tool = ToolForge.define(:tool_name) do
  description 'What the tool does'
  param :input, type: :string
  execute { |input:| output }
end
```

--------------------------------

### description(text = nil)

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-definition.md

Sets or gets the tool description. This description is used by converters to provide context about the tool.

```APIDOC
## description(text = nil)

### Description
Sets or gets the tool description. This description is used by the RubyLLM and MCP converters to provide context about the tool.

### Method
Ruby method

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
#### Method Parameters
- **text** (String) - Optional - The description text to set

### Return Value
`String` or `nil` — The current description when called without arguments; `nil` when called to set.

### Example
```ruby
tool = ToolForge.define(:file_reader) do
  description 'Reads and processes files'
end

# Get description
puts tool.description #=> 'Reads and processes files'
```
```

--------------------------------

### Define a New Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-forge-module.md

Creates a new tool definition instance and executes a block to configure its DSL. Use this to define the name, description, parameters, and execution logic for a tool.

```ruby
def self.define(name, &block)
  ToolDefinition.new(name, &block)
end
```

```ruby
require 'tool_forge'

tool = ToolForge.define(:greet_user) do
  description 'Greets a user with a personalized message'
  
  param :name, type: :string, description: 'User name'
  param :greeting, type: :string, description: 'Greeting style',
        required: false, default: 'Hello'
  
  execute do |name:, greeting:|
    "#{greeting}, #{name}! Welcome to ToolForge!"
  end
end

# Convert to RubyLLM format
ruby_llm_tool = tool.to_ruby_llm_tool
instance = ruby_llm_tool.new
result = instance.execute(name: 'Alice')
#=> "Hello, Alice! Welcome to ToolForge!"
```

--------------------------------

### Tool Definition: Constructor (new)

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Demonstrates instantiating a tool class using its constructor, passing parameters.

```ruby
tool_instance = MyTool.new(input: "some data")
```

--------------------------------

### Define a Basic Tool with Parameters and Execution Logic

Source: https://github.com/afstanton/tool_forge/blob/main/README.md

Use this to define a tool that reads and processes files. It includes parameters for filename, encoding, and maximum lines, along with the core execution logic.

```ruby
tool = ToolForge.define(:file_reader) do
  description 'Reads and processes files'

  # Define parameters with types and validation
  param :filename, type: :string, description: 'Path to file'
  param :encoding, type: :string, required: false, default: 'utf-8'
  param :max_lines, type: :integer, required: false

  # Define execution logic
  execute do |filename:, encoding:, max_lines:|
    content = File.read(filename, encoding: encoding)
    lines = content.lines

    if max_lines
      lines.first(max_lines).join
    else
      content
    end
  end
end
```

--------------------------------

### Set or Get Tool Description

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

The description method on a tool instance can be used to set a new description or retrieve the current one.

```ruby
tool.description 'My tool'         # Set
tool.description                    # Get
```

--------------------------------

### Get ToolForge Version

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/configuration.md

Retrieve the current ToolForge version programmatically. This is useful for logging or implementing version-specific checks within your application.

```ruby
puts ToolForge::VERSION  # => '0.2.2'

# Use in version checks
if ToolForge::VERSION.start_with?('0.2')
  puts 'Using ToolForge 0.2.x'
end
```

--------------------------------

### Run Docker Copy Tool

Source: https://github.com/afstanton/tool_forge/blob/main/examples/README.md

Executes the docker_copy_tool.rb script from the project root.

```bash
ruby examples/docker_copy_tool.rb
```

--------------------------------

### Define a Basic Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-definition.md

Use this for simple tools that perform a single action based on input parameters. Ensure all required parameters are defined.

```ruby
tool = ToolForge.define(:simple_tool) do
  description 'A simple tool that echoes input'
  
  param :message, type: :string, description: 'Message to echo'
  
  execute do |message מד:|
    "Echo: #{message}"
  end
end
```

--------------------------------

### Use Instance Helper Method in RubyLLM Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Demonstrates how an instance helper method defined in ToolForge becomes a regular instance method on the generated RubyLLM tool class. The helper method 'format_text' is used within the 'execute' block.

```ruby
tool_def = ToolForge.define(:text_formatter) do
  description 'Formats text in various ways'
  
  param :text, type: :string
  param :style, type: :string, required: false, default: 'plain'
  
  helper(:format_text) do |text, style|
    case style
    when 'uppercase' then text.upcase
    when 'lowercase' then text.downcase
    when 'title' then text.split.map(&:capitalize).join(' ')
    else text
    end
  end
  
  execute do |text:, style מד:| 
    format_text(text, style)
  end
end

ruby_llm_class = tool_def.to_ruby_llm_tool
instance = ruby_llm_class.new
result = instance.execute(text: 'hello world', style: 'uppercase')
#=> 'HELLO WORLD'
```

--------------------------------

### Documenting Tool Parameters

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Document all parameters with their types and descriptions. Specify if a parameter is required.

```ruby
param :file_path, type: :string, description: 'Absolute or relative path to file'
param :max_lines, type: :integer, required: false, description: 'Maximum number of lines to read'
```

--------------------------------

### Define Class Helper Method

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/INDEX.md

Define class helper methods that can be accessed via `self.class` within the tool's `execute` block. This example shows a `validate` helper.

```ruby
class_helper(:validate) { |input| !input.empty? }
execute { |input:| self.class.validate(input) }
```

--------------------------------

### Define a Basic Tool with ToolForge

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Defines a tool named 'echo' with a description, a required string parameter 'text', and an optional integer parameter 'repeat'. The 'execute' block specifies the tool's behavior.

```ruby
require 'tool_forge'

tool_def = ToolForge.define(:echo) do
  description 'Echoes back the input text'
  
  param :text, type: :string, description: 'The text to echo'
  param :repeat, type: :integer, required: false, default: 1
  
  execute do |text:, repeat מד:| 
    ([text] * repeat).join("\n")
  end
end
```

--------------------------------

### Best Practice: Framework-Specific Conversions

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Implements conversion methods for target frameworks like RubyLLM and MCP.

```ruby
def to_ruby_llm_tool
  # ...
end

def to_mcp_tool
  # ...
end
```

--------------------------------

### Multi-Framework Tool Registration

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Shows how to define a tool once using Tool Forge and then register it with both RubyLLM and MCP. This ensures that the same tool logic is available and behaves identically across different frameworks.

```ruby
require 'ruby_llm'
require 'mcp'
require 'tool_forge'

# Define tool once
file_reader_tool = ToolForge.define(:read_file) do
  description 'Reads a file and returns its content'
  
  param :file_path, type: :string, description: 'Path to file'
  param :max_lines, type: :integer, required: false, description: 'Max lines to read'
  
  helper(:read_with_limit) do |path, max_lines|
    lines = File.readlines(path)
    max_lines ? lines.first(max_lines) : lines
  end
  
  execute do |file_path:, max_lines: nil|
    return { error: 'File not found' } unless File.exist?(file_path)
    lines = read_with_limit(file_path, max_lines)
    { content: lines.join, line_count: lines.count }
  end
end

# Register with RubyLLM
ruby_llm_client = RubyLLM::Client.new
ruby_llm_client.add_tool(file_reader_tool.to_ruby_llm_tool)

# Register with MCP
mcp_server = MCP::Server.new
mcp_server.add_tool(file_reader_tool.to_mcp_tool)

# Both frameworks now have access to the same tool with same behavior
```

--------------------------------

### Integrate Docker Copy Tool with RubyLLM

Source: https://github.com/afstanton/tool_forge/blob/main/examples/README.md

Converts the docker_copy_tool to RubyLLM format and adds it to a RubyLLM client.

```ruby
require 'ruby_llm'
require_relative 'docker_copy_tool'

# Convert to RubyLLM format
ruby_llm_tool = docker_copy_tool.to_ruby_llm_tool

# Use with RubyLLM framework
llm = RubyLLM::Client.new
llm.add_tool(ruby_llm_tool)
```

--------------------------------

### Best Practice: Clear Descriptions

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Ensures tools have descriptive text for clarity and framework integration.

```ruby
description("This tool fetches user data based on ID.")
```

--------------------------------

### Define Tool with Description

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/configuration.md

Always set a clear, concise description for your tool. This helps users understand its purpose immediately.

```ruby
tool = ToolForge.define(:my_tool) do
  description 'A clear, actionable description of what this tool does'
  # ...
end
```

--------------------------------

### Create a Tool Definition

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Defines a new tool with its description, parameters, and execution logic.

```APIDOC
## Create a Tool Definition

### Description
Defines a new tool with its description, parameters, and execution logic.

### Method
ToolForge.define

### Parameters
- **tool_name** (Symbol) - Required - The name of the tool.

### DSL Methods within `define` block:
- `description(text)`: Sets or gets the tool description.
- `param(name, **options)`: Defines a parameter for the tool. Options include `type`, `description`, `required`, and `default`.
- `execute(&block)`: Defines the execution logic for the tool.
- `helper(name, &block)`: Defines an instance helper method.
- `class_helper(name, &block)`: Defines a class helper method.

### Return
`ToolDefinition` instance
```

--------------------------------

### ToolDefinition Constructor

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/api-reference/tool-definition.md

Initializes a new ToolDefinition instance. It sets up default values for attributes and evaluates a configuration block if provided, enabling DSL-based configuration.

```ruby
def initialize(name, &block)
  @name = name
  @description = nil
  @params = []
  @execute_block = nil
  @helper_methods = { instance: {}, class: {} }

  instance_eval(&block) if block_given?
end
```

--------------------------------

### Define and Use ToolForge with RubyLLM and MCP

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/examples.md

Defines a 'weather' tool with parameters and a helper method, then converts it to RubyLLM and MCP tool formats for execution. This snippet requires the 'ruby_llm', 'mcp', and 'tool_forge' gems.

```ruby
require 'ruby_llm'
require 'mcp'
require 'tool_forge'

# Single tool definition
weather_tool = ToolForge.define(:weather) do
  description 'Gets weather information for a location'
  
  param :location, type: :string
  param :unit, type: :string, required: false, default: 'celsius'
  
  helper(:get_weather) do |location|
    { location: location, temperature: 72, condition: 'sunny' }
  end
  
  execute do |location:, unit:|
    weather = get_weather(location)
    weather[:unit] = unit
    weather
  end
end

# Use with both frameworks
# RubyLLM
ruby_llm_class = weather_tool.to_ruby_llm_tool
llm_instance = ruby_llm_class.new
result = llm_instance.execute(location: 'New York')

# MCP
mcp_class = weather_tool.to_mcp_tool
response = mcp_class.call(server_context: nil, location: 'London', unit: 'fahrenheit')

puts "Both frameworks execute the same tool definition"
```

--------------------------------

### Access ToolDefinition Attributes

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/types.md

Demonstrates how to define a tool and then access its various attributes, such as name, parameters, execute block, helper methods, and description, using a `ToolForge.define` block.

```ruby
tool = ToolForge.define(:my_tool) do
  description 'My tool'
  param :input, type: :string
  execute { |input:| input.upcase }
end

puts tool.name                          #=> :my_tool
puts tool.params.length                #=> 1
puts tool.params.first[:name]           #=> :input
puts tool.execute_block.class           #=> Proc
puts tool.helper_methods.keys           #=> [:instance, :class]
puts tool.description                   #=> 'My tool'
```

--------------------------------

### Run File Processor Tool

Source: https://github.com/afstanton/tool_forge/blob/main/examples/README.md

Executes the file_processor_tool.rb script from the project root.

```bash
ruby examples/file_processor_tool.rb
```

--------------------------------

### Check Tool Helper Methods

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/quick-reference.md

Inspect the available instance and class helper methods for a tool.

```ruby
tool.helper_methods[:instance].keys  # Instance helpers
tool.helper_methods[:class].keys     # Class helpers
```

--------------------------------

### Framework Behavior: Response Formatting

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

Explains how tool responses are formatted for different frameworks, such as JSON for MCP.

```ruby
# Example of response formatting for MCP
def to_mcp_tool(response_format: :json)
  # ...
end
```

--------------------------------

### Using Helper Methods with MCP Tools

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/integration-guide.md

Define and use both instance and class helper methods within ToolForge tools for MCP integration. These helpers can encapsulate reusable logic for data cleaning or output formatting.

```ruby
tool_def = ToolForge.define(:data_processor) do
  description 'Processes data with helper methods'
  
  param :data, type: :array
  
  # Instance helper
  helper(:clean_data) do |data|
    data.compact.map(&:strip).uniq
  end
  
  # Class helper
  class_helper(:format_output) do |data|
    { processed: true, count: data.length, items: data }
  end
  
  execute do |data:|
    cleaned = clean_data(data)
    self.class.format_output(cleaned)
  end
end

mcp_tool_class = tool_def.to_mcp_tool
response = mcp_tool_class.call(
  server_context: nil,
  data: ['hello', ' world', 'hello', nil]
)
# Response: { "processed": true, "count": 2, "items": ["hello", "world"] }
```

--------------------------------

### Define a Basic Tool

Source: https://github.com/afstanton/tool_forge/blob/main/_autodocs/00-START-HERE.md

Defines a simple tool named 'my_tool' with a description, a string parameter, a helper method, and an execute block. The helper method formats the result by converting it to uppercase.

```ruby
require 'tool_forge'

tool = ToolForge.define(:my_tool) do
  description 'What your tool does'
  param :input, type: :string, description: 'Input description'
  
  helper(:format_result) { |result| result.upcase }
  
  execute do |input מד:|
    output = input.reverse
    format_result(output)
  end
end
```

--------------------------------

### Define a Tool with Instance Helper Methods

Source: https://github.com/afstanton/tool_forge/blob/main/README.md

Define a tool that processes text and uses instance helper methods for formatting and adding prefixes. Ensure helper methods are defined within the `helper` block.

```ruby
tool = ToolForge.define(:text_processor) do
  description 'Processes text with formatting'

  param :text, type: :string
  param :format, type: :string, default: 'uppercase'

  # Instance helper method
  helper(:format_text) do |text, format|
    case format
    when 'uppercase' then text.upcase
    when 'lowercase' then text.downcase
    when 'title' then text.split.map(&:capitalize).join(' ')
    else text
    end
  end

  helper(:add_prefix) do |text|
    "PROCESSED: #{text}"
  end

  execute do |text:, format:|
    formatted = format_text(text, format)
    add_prefix(formatted)
  end
end
```