Tools

The tools/ package parses function-call output from models that support tool use and matches it against the user-declared tool definitions.

Purpose

Function calling has become a standard feature across models, but each family emits tool calls in a slightly different format (JSON inside special tokens, XML-ish tags, harmony channels). The tools package centralizes the parsing so handlers can rely on a single ToolCall shape.

Key abstractions

Symbol	Location	Purpose
Tool	tools/	Definition: name, description, JSON Schema parameters. Mirrors the shape in api/types.go.
ToolCall	tools/	Parsed call: name, arguments map.
Stream parser	tools/	Reads partial tokens and emits ToolCalls as they complete.

How it works

graph LR
    Stream[token stream] --> Parser[tools parser]
    Parser -->|matches a registered Tool| ToolCall[ToolCall]
    Parser -->|else| Text[plain text]

The parser is shaped to recognize the most common formats: top-level JSON object with name + arguments, harmony channel-tagged calls, and XML-ish wrappers used by some models. Models that use a custom format are handled by their own parser under model/parsers/ (see model engine).

Integration points

• Used by Server.ChatHandler (server/routes.go) when the request includes tools.
• Used by the OpenAI-compatible /v1/chat/completions middleware to translate tool_calls field both ways (middleware/openai.go).
• Emitted by the interactive CLI (cmd/interactive.go) as a styled block.

Entry points for modification

• A new common tool-call format → extend the parser in tools/ so all models benefit.
• A model-family-specific format → add a parser under model/parsers/<family>/ and wire it through server/renderer_resolution.go.

Key source files

File	Purpose
tools/	The shared tool-call parser.
api/types.go	The Tool and ToolCall types in the public API.
server/routes.go	Caller in ChatHandler.