#Tool Package

#Core Types

#ToolDesc

///|
pub struct ToolDesc {
  description : String
  name : String
  schema : JsonSchema
} derive(ToJson, Eq, Show)

• description: Human-readable description for the AI
• name: Unique identifier for the tool
• schema: JSON Schema defining the expected parameters

#Tool[Output]

///|
pub struct Tool[Output] {
  desc : ToolDesc
  // private: f : ToolFn[Output]
}

#ToolFn[Output]

///|
pub(all) struct ToolFn[Output](async (Json) -> ToolResult[Output] noraise)

#ToolResult[Output]

///|
pub enum ToolResult[Output] {
  Ok(Output)
  Error(Error, String)
} derive(ToJson)

#AgentTool

///|
type AgentTool // Wraps Tool[(Json, String)]

#JsonSchema

///|
pub(all) struct JsonSchema(Json)

#Key APIs

#Tool Creation

pub fn[Output] Tool::new(
  description~ : String,
  name~ : String,
  schema~ : JsonSchema,
  f : ToolFn[Output],
) -> Tool[Output]

#Tool Execution

pub async fn[Output] Tool::call(
  tool : Tool[Output],
  args : Json,
) -> ToolResult[Output] noraise

#Result Constructors

pub fn[Output] ToolResult::ok(output : Output) -> ToolResult[Output]
pub fn[Output] ToolResult::error(
  output : String,
  error? : Error,
) -> ToolResult[Output]

#Conversion to AgentTool

pub fn[Output : ToJson + Show] Tool::to_agent_tool(
  self : Tool[Output],
) -> AgentTool

#OpenAI Conversion

pub fn ToolDesc::to_openai(
  tool_desc : ToolDesc,
) -> @openai.ChatCompletionToolParam

#Creating a Custom Tool

// Define the output type

///|
struct WeatherOutput {
  temperature : Double
  conditions : String
} derive(ToJson, Show)

// Define the JSON schema

///|
let weather_schema : @tool.JsonSchema = {
  "type": "object",
  "properties": { "location": { "type": "string", "description": "City name" } },
  "required": ["location"],
}

// Create the tool

///|
let weather_tool : @tool.Tool[WeatherOutput] = @tool.new(
  description="Get current weather for a location",
  name="get_weather",
  schema=weather_schema,
  @tool.ToolFn(async fn(args) -> @tool.ToolResult[WeatherOutput] noraise {
    guard args is { "location": String(location), .. } else {
      return @tool.error("Missing 'location' parameter")
    }

    // Simulate weather API call
    @tool.ok({ temperature: 72.5, conditions: "Sunny" })
  }),
)

// Convert for agent use

///|
let agent_tool = weather_tool.to_agent_tool()

#Tool Execution Flow

AI Model
    │
    ▼
Tool Call Request (JSON arguments)
    │
    ▼
Tool::call(args)
    │
    ├─► Validate args against schema
    │
    ├─► Execute ToolFn
    │
    ▼
ToolResult
    │
    ├─► Ok(Output) ──► to_json() ──► Return to AI
    │
    └─► Error(Error, String) ──► Return error message

#AgentTool vs Tool[Output]

• Tool[Output]: Generic tool with custom output type
• AgentTool: Tool adapted for agent use with (Json, String) output
  • Json: Structured result for AI consumption
  • String: Human-readable rendering

#Usage with Agent

// Create tools
let cmd_tool = @execute_command.new(job_manager).to_agent_tool()
let file_tool = @read_file.new(file_manager).to_agent_tool()

// Add to agent
agent.add_tools([cmd_tool, file_tool])

#Dependencies

• openai: OpenAI API types for conversion
• json: JSON handling