Anvia Docs

Import from @anvia/core or @anvia/core/tool.

Tool

interface Tool<Args = unknown, Output = unknown> {
  readonly name: string;
  definition(prompt: string): ToolDefinition | Promise<ToolDefinition>;
  call(args: Args): Output | Promise<Output>;
}

Purpose: normalized callable tool contract.

Return behavior: definition(...) exposes provider JSON schema; call(...) executes local logic.

Notable errors: tool implementations can throw arbitrary errors.

createTool and CreateToolOptions

type CreateToolOptions<InputSchema extends ZodSchema, OutputSchema extends ZodSchema | undefined = undefined> = {
  name: string;
  description: string;
  input: InputSchema;
  output?: OutputSchema;
  execute(args: z.output<InputSchema>): unknown | Promise<unknown>;
};

function createTool<InputSchema extends ZodSchema, OutputSchema extends ZodSchema | undefined = undefined>(
  options: CreateToolOptions<InputSchema, OutputSchema>,
): Tool<z.input<InputSchema>, ToolOutput<OutputSchema>>;

Purpose: create a typed tool from Zod input and optional output schemas.

Return behavior: parses arguments before execution and parses output when an output schema is supplied.

Notable errors: input or output validation errors throw from call(...); schema conversion can throw during creation.

ToolSet

class ToolSet {
  static fromTools(tools: Tool[]): ToolSet;
  addTool(tool: Tool): this;
  addTools(toolSet: ToolSet): this;
  deleteTool(toolName: string): boolean;
  contains(toolName: string): boolean;
  get(toolName: string): Tool | undefined;
  values(): Tool[];
  getToolDefinitions(prompt?: string): Promise<ToolDefinition[]>;
  call(toolName: string, args: string): Promise<string>;
}

Purpose: storage and execution boundary for concrete tool implementations.

Return behavior: call(...) parses JSON args, executes the matching tool, and serializes the output as a string.

Notable errors: throws ToolNotFoundError, ToolJsonError, or ToolCallError.

ToolRegistry

class ToolRegistry {
  static fromTools(tools: Tool[]): ToolRegistry;
  addTool(tool: Tool): this;
  addTools(tools: Tool[]): this;
  addToolSet(toolSet: ToolSet, exposedToolNames?: string[]): this;
  removeTool(toolName: string): boolean;
  callTool(toolName: string, args: string): Promise<string>;
  getToolDefinitions(prompt?: string): Promise<ToolDefinition[]>;
}

Purpose: controls which tools are available to a model while retaining callable tool implementations.

Return behavior: getToolDefinitions(...) returns definitions only for exposed tools.

Notable errors: callTool(...) forwards ToolSet.call(...) errors.

createThinkTool

type CreateThinkToolOptions = {
  name?: string;
  description?: string;
};

function createThinkTool(options?: CreateThinkToolOptions): Tool<{ thought: string }, string>;

Purpose: create a built-in private reasoning tool that echoes a thought string.

Return behavior: returns a tool named think unless overridden.

Notable errors: validation errors can occur if the model calls it with invalid arguments.

Serialization Helpers

function serializeToolOutput(output: unknown): string;
function parseToolArgs(args: string): JsonValue;

Purpose: convert tool outputs and model-supplied argument strings.

Return behavior: parseToolArgs("") returns {}; serializeToolOutput(...) returns strings unchanged and JSON-stringifies other values.

Notable errors: parseToolArgs(...) throws SyntaxError for invalid JSON.

Error Classes

class ToolCallError extends Error {
  readonly cause?: unknown;
}

class ToolNotFoundError extends Error {
  readonly toolName: string;
}

class ToolJsonError extends Error {
  readonly cause?: unknown;
}

Purpose: typed failures from ToolSet.call(...).

Return behavior: thrown errors.

Notable errors: these are the notable tool errors.

For workflow guidance, see Creating Tools.