pig/tool

Tool types and registry for the pig agent library.

A Tool pairs a ToolDefinition (schema for the LLM) with a handler function. The handler receives library-owned immutable invocation context and parsed dynamic.Dynamic arguments, and returns a json.Json result or structured ToolError.

Types

Tool

</>

A tool pairs a definition (shown to the LLM) with a handler function. The handler receives immutable call context and parsed JSON arguments.

pub type Tool {
  Tool(
    definition: tool_definition.ToolDefinition,
    handler: fn(ToolCallContext, dynamic.Dynamic) -> Result(
      json.Json,
      ToolError,
    ),
  )
}

Constructors

Tool(
  definition: tool_definition.ToolDefinition,
  handler: fn(ToolCallContext, dynamic.Dynamic) -> Result(
    json.Json,
    ToolError,
  ),
)

ToolCallBatchError

</>

Deterministic reason a tool-call batch is invalid.

pub type ToolCallBatchError {
  EmptyToolCallId(index: Int)
  DuplicateToolCallId(call_id: String)
}

Constructors

```
EmptyToolCallId(index: Int)
```
```
DuplicateToolCallId(call_id: String)
```

ToolCallContext

opaque </>

Immutable identity of a tool invocation.

Contexts are created from protocol tool calls by pig’s canonical dispatch; handlers can inspect them but cannot manufacture or alter them.

pub opaque type ToolCallContext

ToolError

</>

Structured error from tool execution.

pub type ToolError {
  ToolError(message: String)
  InvalidToolCallBatch(error: ToolCallBatchError)
}

Constructors

```
ToolError(message: String)
```

InvalidToolCallBatch(error: ToolCallBatchError)

ToolPrompt

</>

A tool’s name and description for composing into a system prompt.

pub type ToolPrompt {
  ToolPrompt(name: String, description: String)
}

Constructors

ToolPrompt(name: String, description: String)

ToolRegistry

</>

A registry of tools indexed by name.

pub type ToolRegistry {
  ToolRegistry(entries: dict.Dict(String, Tool))
}

Constructors

ToolRegistry(entries: dict.Dict(String, Tool))

Values

call_id

</>

pub fn call_id(context: ToolCallContext) -> String

Return the protocol call ID for this invocation.

error_message

</>

pub fn error_message(error: ToolError) -> String

Render a structured tool error for tool-result messages and users.

execute_tool

</>

pub fn execute_tool(
  registry: ToolRegistry,
  call: message.ToolCall,
) -> Result(json.Json, ToolError)

Execute a protocol tool call through its registry-selected handler.

The call name selects the registered tool; that same call is decoded and supplies the immutable context passed to its handler. Returns structured errors for unknown tools, malformed arguments, or handler failures.

list_definitions

</>

pub fn list_definitions(
  registry: ToolRegistry,
) -> List(tool_definition.ToolDefinition)

List all tool definitions in the registry.

list_tool_prompts

</>

pub fn list_tool_prompts(
  registry: ToolRegistry,
) -> List(ToolPrompt)

Extract name and description from each tool in the registry. Used to auto-compose an “Available tools” section in the system prompt.

lookup

</>

pub fn lookup(
  registry: ToolRegistry,
  name: String,
) -> Result(Tool, Nil)

Look up a tool by name. Returns Error(Nil) if not found.

new_registry

</>

pub fn new_registry() -> ToolRegistry

Create an empty tool registry.

register

</>

pub fn register(
  registry: ToolRegistry,
  tool: Tool,
) -> ToolRegistry

tool_name

</>

pub fn tool_name(context: ToolCallContext) -> String

Return the requested tool name for this invocation.