tools

Documentation

Overview

Package tools defines tool contracts and implementations.

Includes:

• ToolDefinition: name, description, JSON input schema, handler.
• GenerateSchema[T](): derive JSON Schema from Go structs.
• File tools: read_file, list_files (non-recursive), edit_file.
• Invariants: tool_use and its corresponding tool_result remain adjacent within a turn.

Index

• Variables
• func EditFile(input json.RawMessage) (string, error)
• func GenerateSchema[T any]() anthropic.ToolInputSchemaParam
• func ListFiles(input json.RawMessage) (string, error)
• func ReadFile(input json.RawMessage) (string, error)
• type EditFileInput
• type ListFilesInput
• type ReadFileInput
• type ToolDefinition
  • func Registry() []ToolDefinition

Variables

var EditFileDefinition = ToolDefinition{
	Name: "edit_file",
	Description: `Create or modify a text file addressed by a relative path within the workspace.

When old_str is empty and the file doesn’t exist, a new file is created.

When editing an existing file, all occurrences of old_str are replaced with new_str; old_str and new_str must be different.
`,
	InputSchema: EditFileInputSchema,
	Function:    EditFile,
}

var EditFileInputSchema = GenerateSchema[EditFileInput]()

var ListFilesDefinition = ToolDefinition{
	Name:        "list_files",
	Description: "List names of files in a directory within the workspace (non-recursive).",
	InputSchema: ListFilesInputSchema,
	Function:    ListFiles,
}

var ListFilesInputSchema = GenerateSchema[ListFilesInput]()

var ReadFileDefinition = ToolDefinition{
	Name:        "read_file",
	Description: "Read the contents of a file addressed by a relative file path within the workspace. Directory paths and unsafe paths are rejected.",
	InputSchema: ReadFileInputSchema,
	Function:    ReadFile,
}

var ReadFileInputSchema = GenerateSchema[ReadFileInput]()

Functions

func EditFile

func EditFile(input json.RawMessage) (string, error)

func GenerateSchema

func GenerateSchema[T any]() anthropic.ToolInputSchemaParam

func ListFiles

func ListFiles(input json.RawMessage) (string, error)

ListFiles lists non-recursive directory entries under the sandbox via fsops, then applies deterministic sorting and simple paging at the tool layer. Defaults:

• page: 1 when <= 0
• page_size: 200 when <= 0

Contract: returns a JSON-encoded []string to preserve existing tool behaviour.

func ReadFile

func ReadFile(input json.RawMessage) (string, error)

ReadFile reads a file via fsops (sandbox/policy) and applies small, deterministic caps for LLM-facing pagination:

• offset: 0-based starting line (negatives clamped to 0)
• limit: number of lines to return (<= defaults to 200)

If not all lines are returned, it appends a trailing sentinel to signal pagination. Rationale: keep tool results predictably small for windowing/token heuristics.

Types

type EditFileInput

type EditFileInput struct {
	Path   string `json:"path" jsonschema_description:"Target relative file path"`
	OldStr string `json:"old_str" jsonschema_description:"Exact text to replace; must be present once when editing an existing file."`
	NewStr string `json:"new_str" jsonschema_description:"New text to write or replace old_str with"`
}

type ListFilesInput

type ListFilesInput struct {
	Path     string `json:"path,omitempty" jsonschema_description:"Optional relative path to list files from (defaults to current directory)."`
	Page     int    `json:"page,omitempty" jsonschema_description:"1-based page number (default 1)."`
	PageSize int    `json:"page_size,omitempty" jsonschema_description:"Page size (default 200)."`
}

type ReadFileInput

type ReadFileInput struct {
	Path   string `json:"path" jsonschema_description:"Relative file path."`
	Offset int    `json:"offset,omitempty" jsonschema_description:"Line offset (0-based) to start reading from."`
	Limit  int    `json:"limit,omitempty" jsonschema_description:"Maximum lines to return from offset (default 200)."`
}

type ToolDefinition

type ToolDefinition struct {
	Name        string                         `json:"name"`
	Description string                         `json:"description"`
	InputSchema anthropic.ToolInputSchemaParam `json:"input_schema"`
	Function    func(input json.RawMessage) (string, error)
}

func Registry

func Registry() []ToolDefinition

Registry returns all tool definitions wired for the agent