builder

Fluent builder for tool definitions

This module provides an ergonomic builder API for creating tool definitions. The builder pattern allows for type-safe, readable tool construction.

Example

let weather_tool =
  tool_builder("get_weather")
  |> with_description("Get the current weather for a location")
  |> add_string_param("location", "City and state, e.g. 'San Francisco, CA'", True)
  |> add_enum_param("unit", "Temperature unit", ["celsius", "fahrenheit"], False)
  |> build()

// For tools with no parameters
let time_tool =
  tool_builder("get_time")
  |> with_description("Get the current time")
  |> build_simple()

Types

ToolBuilder

</>

Builder state for constructing a Tool

pub type ToolBuilder {
  ToolBuilder(
    name: String,
    description: option.Option(String),
    properties: List(#(String, tool.PropertySchema)),
    required: List(String),
  )
}

Constructors

ToolBuilder(
  name: String,
  description: option.Option(String),
  properties: List(#(String, tool.PropertySchema)),
  required: List(String),
)

Arguments

name: Name of the tool
description: Optional description
properties: Properties accumulated so far
required: Required property names

ToolBuilderError

</>

Validation error for tool definitions

pub type ToolBuilderError {
  InvalidToolName(error: tool.ToolNameError)
  DuplicateProperty(name: String)
}

Constructors

InvalidToolName(error: tool.ToolNameError)

Tool name validation failed

```
DuplicateProperty(name: String)
```
Duplicate property name

Values

add_boolean_param

</>

pub fn add_boolean_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  is_required: Bool,
) -> ToolBuilder

Add a boolean parameter

add_enum_param

</>

pub fn add_enum_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  values: List(String),
  is_required: Bool,
) -> ToolBuilder

Add an enum parameter (string with allowed values)

add_integer_param

</>

pub fn add_integer_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  is_required: Bool,
) -> ToolBuilder

Add an integer parameter

add_number_array_param

</>

pub fn add_number_array_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  is_required: Bool,
) -> ToolBuilder

Add an array parameter with number items

add_number_param

</>

pub fn add_number_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  is_required: Bool,
) -> ToolBuilder

Add a number parameter

add_object_param

</>

pub fn add_object_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  nested_properties: List(#(String, tool.PropertySchema)),
  nested_required: List(String),
  is_required: Bool,
) -> ToolBuilder

Add an object parameter with nested properties

add_property

</>

pub fn add_property(
  builder: ToolBuilder,
  name: String,
  property: tool.PropertySchema,
  is_required: Bool,
) -> ToolBuilder

Add a custom property schema

add_string_array_param

</>

pub fn add_string_array_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  item_description: String,
  is_required: Bool,
) -> ToolBuilder

Add an array parameter with string items

add_string_param

</>

pub fn add_string_param(
  builder: ToolBuilder,
  name: String,
  description: String,
  is_required: Bool,
) -> ToolBuilder

Add a string parameter

build

</>

pub fn build(builder: ToolBuilder) -> tool.Tool

Build the tool from the builder state without validation.

Use this when you trust the tool name is valid (e.g., hardcoded constants). For untrusted input, use build_validated() instead.

build_simple

</>

pub fn build_simple(builder: ToolBuilder) -> tool.Tool

Build a simple tool with no parameters without validation.

Use this when you trust the tool name is valid (e.g., hardcoded constants). For untrusted input, use build_validated() instead.

build_validated

</>

pub fn build_validated(
  builder: ToolBuilder,
) -> Result(tool.Tool, ToolBuilderError)

Build and validate the tool.

This validates that:

The tool name matches Anthropic’s requirements (alphanumeric, _, -, 1-64 chars)
No duplicate property names exist

Use this for user-provided or untrusted tool names.

builder_error_to_string

</>

pub fn builder_error_to_string(error: ToolBuilderError) -> String

Convert a ToolBuilderError to a human-readable string

tool_builder

</>

pub fn tool_builder(name: String) -> ToolBuilder

Start building a new tool with the given name

tool_builder_with_description

</>

pub fn tool_builder_with_description(
  name: String,
  description: String,
) -> ToolBuilder

Start building a new tool with name and description

validate_name

</>

pub fn validate_name(
  name: String,
) -> Result(tool.ToolName, ToolBuilderError)

Validate a tool name according to Anthropic’s requirements.

Must match regex: ^[a-zA-Z0-9_-]{1,64}$

Returns the validated ToolName on success.

with_description

</>

pub fn with_description(
  builder: ToolBuilder,
  description: String,
) -> ToolBuilder

Set the description for the tool