Tool API

Tool wraps parameter validation, function execution, and tool results. For usage, see add tools.

Constructor parameters

new Tool({ name, description, parametersZodSchema, func })

All four fields are required. Tool uses generics to infer the parameter type of func. The internal constructor type ToolConfig is not exported separately.

An instance’s name, description, parametersZodSchema, and func are public readonly properties.

execute()

execute(args: unknown, options: { callId: string }): Promise<ToolMessage>

Execution order: validate with Zod’s synchronous parse() → await func() → serialize the result with JSON.stringify().

• Success returns a ToolMessage with isError: false.
• If validation, execution, or serialization throws, the returned ToolMessage has isError: true, with String(error) as toolOutput.
• The caller provides callId. It is preserved in the result to associate it with the tool call.

Return values that JSON.stringify() can turn into strings. Avoid undefined, functions, Symbols, and other values that do not produce valid output text. BigInt and circular references can cause serialization failures.

Agent normally calls this method automatically. To execute a tool directly:

import { Tool } from "@yong_xie/lighter";
import * as z from "zod";

const add = new Tool({
  name: "add",
  description: "Calculate the sum of two numbers.",
  parametersZodSchema: z.strictObject({ a: z.number(), b: z.number() }),
  func: ({ a, b }) => a + b,
});

// Validate before executing. toolOutput in the result is the string "42".
const result = await add.execute({ a: 19, b: 23 }, { callId: "call_add_1" });
console.log(result);

getSpec()

getSpec(): ToolSpec

Converts the parameter schema to JSON Schema and returns a tool definition for the model, without the execution function. Conversion uses Zod’s input mode. Unsupported schemas may throw here.

ToolSpec contains:

strict: false is a definition option sent to the provider. It does not disable local Zod validation before tool execution.