tools

Documentation

Overview

Package tools provides structured tool definitions for LLM tool-use.

This package is the foundation of Buckley's tool-use-first architecture. Instead of parsing model text output, we define structured contracts that models fill via tool calls.

Index

• Variables
• func Register(def Definition) error
• type Definition
  • func Get(name string) (Definition, bool)
  • func List() []Definition
  • func (d Definition) ToAnthropicFormat() map[string]any
  • func (d Definition) ToOpenAIFormat() map[string]any
• type Property
  • func ArrayProperty(desc string, items Property) Property
  • func BoolProperty(desc string) Property
  • func IntProperty(desc string) Property
  • func NumberProperty(desc string) Property
  • func StringEnumProperty(desc string, values ...string) Property
  • func StringProperty(desc string) Property
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Get(name string) (Definition, bool)
  • func (r *Registry) List() []Definition
  • func (r *Registry) Names() []string
  • func (r *Registry) Register(def Definition) error
  • func (r *Registry) Subset(names ...string) *Registry
  • func (r *Registry) ToAnthropicFormat() []map[string]any
  • func (r *Registry) ToOpenAIFormat() []map[string]any
• type Schema
  • func ObjectSchema(props map[string]Property, required ...string) Schema
• type ToolCall
  • func (tc ToolCall) Unmarshal(v any) error
• type ToolResult
  • func NewToolError(callID string, err error) ToolResult
  • func NewToolResult(callID string, content any) (ToolResult, error)

Variables

var DefaultRegistry = NewRegistry()

DefaultRegistry is the global tool registry. One-shot commands register their tools here at init time.

Functions

func Register

func Register(def Definition) error

Register adds a tool to the default registry.

Types

type Definition

type Definition struct {
	// Name is the tool identifier (e.g., "generate_commit")
	Name string `json:"name"`

	// Description explains what the tool does (shown to the model)
	Description string `json:"description"`

	// Parameters defines the JSON schema for tool arguments
	Parameters Schema `json:"parameters"`
}

Definition describes a tool that a model can call. This is the contract between Buckley and the model.

func Get

func Get(name string) (Definition, bool)

Get returns a tool from the default registry.

func List

func List() []Definition

List returns all tools from the default registry.

func (Definition) ToAnthropicFormat

func (d Definition) ToAnthropicFormat() map[string]any

ToAnthropicFormat converts the definition to Anthropic tool format. This is used for Claude and other Anthropic models.

func (Definition) ToOpenAIFormat

func (d Definition) ToOpenAIFormat() map[string]any

ToOpenAIFormat converts the definition to OpenAI function calling format. This is used for models that support OpenAI-style tool use.

type Property

type Property struct {
	Type        string    `json:"type"`
	Description string    `json:"description,omitempty"`
	Enum        []string  `json:"enum,omitempty"`
	Items       *Property `json:"items,omitempty"`
	MaxLength   int       `json:"maxLength,omitempty"`
	MinLength   int       `json:"minLength,omitempty"`
	MinItems    int       `json:"minItems,omitempty"`
	MaxItems    int       `json:"maxItems,omitempty"`
	Default     any       `json:"default,omitempty"`
	Minimum     *float64  `json:"minimum,omitempty"`
	Maximum     *float64  `json:"maximum,omitempty"`
}

Property defines a single property in a JSON Schema.

func ArrayProperty

func ArrayProperty(desc string, items Property) Property

ArrayProperty creates an array property with the given item type.

func BoolProperty

func BoolProperty(desc string) Property

BoolProperty creates a boolean property.

func IntProperty

func IntProperty(desc string) Property

IntProperty creates an integer property.

func NumberProperty

func NumberProperty(desc string) Property

NumberProperty creates a number property.

func StringEnumProperty

func StringEnumProperty(desc string, values ...string) Property

StringEnumProperty creates a string property constrained to specific values.

func StringProperty

func StringProperty(desc string) Property

StringProperty creates a string property with optional constraints.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages tool definitions. It provides a central place to register and look up tools.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty tool registry.

func (*Registry) Get

func (r *Registry) Get(name string) (Definition, bool)

Get returns a tool definition by name.

func (*Registry) List

func (r *Registry) List() []Definition

List returns all registered tool definitions.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns all registered tool names.

func (*Registry) Register

func (r *Registry) Register(def Definition) error

Register adds a tool definition to the registry. Returns an error if a tool with the same name already exists.

func (*Registry) Subset

func (r *Registry) Subset(names ...string) *Registry

Subset returns a new registry containing only the named tools. Tools that don't exist in the source registry are silently skipped.

func (*Registry) ToAnthropicFormat

func (r *Registry) ToAnthropicFormat() []map[string]any

ToAnthropicFormat returns all tools in Anthropic tool format.

func (*Registry) ToOpenAIFormat

func (r *Registry) ToOpenAIFormat() []map[string]any

ToOpenAIFormat returns all tools in OpenAI function calling format.

type Schema

type Schema struct {
	Type        string              `json:"type"`
	Description string              `json:"description,omitempty"`
	Properties  map[string]Property `json:"properties,omitempty"`
	Required    []string            `json:"required,omitempty"`
	Enum        []string            `json:"enum,omitempty"`
}

Schema defines a JSON Schema for tool parameters. This is sent to the model so it knows the exact structure to return.

func ObjectSchema

func ObjectSchema(props map[string]Property, required ...string) Schema

ObjectSchema creates a schema for an object type with the given properties.

type ToolCall

type ToolCall struct {
	// ID is the unique identifier for this tool call (from the model)
	ID string `json:"id"`

	// Name is the tool that was called
	Name string `json:"name"`

	// Arguments is the raw JSON arguments from the model
	Arguments json.RawMessage `json:"arguments"`
}

ToolCall represents a tool invocation from a model response.

func (ToolCall) Unmarshal

func (tc ToolCall) Unmarshal(v any) error

Unmarshal decodes the tool call arguments into the given type.

type ToolResult

type ToolResult struct {
	// CallID matches the ToolCall.ID this is responding to
	CallID string `json:"tool_call_id"`

	// Content is the result content (usually JSON or text)
	Content string `json:"content"`

	// IsError indicates if the tool execution failed
	IsError bool `json:"is_error,omitempty"`
}

ToolResult represents the result of executing a tool.

func NewToolError

func NewToolError(callID string, err error) ToolResult

NewToolError creates an error tool result.

func NewToolResult

func NewToolResult(callID string, content any) (ToolResult, error)

NewToolResult creates a successful tool result.