defineTool

defineTool creates a validated, type-safe tool definition usable by Agent.

import { defineTool } from "kenpachi";

Parameters

ToolDefinition

required

Configuration object describing tool behavior:

Show ToolDefinition Properties

string

required

The tool name passed to the model (must contain alphanumeric characters or underscores).

string

required

Clear description telling the LLM when and how to use the tool.

z.ZodType<Args>

required

Zod schema defining expected parameters. Automatically converted into standard JSON Schema (type: "object", properties, required) for LLM model tool arrays via serializeZodSchema.

(args: Args, ctx: ToolContext) => Promise<Result>

required

Async function executing tool logic with validated arguments.

boolean

default:"true"

Whether kenpachi should attempt argument repair and retry on schema validation failures.

ToolContext Parameter

The execute function receives a ToolContext instance as its second argument:

Record<string, unknown>

KeyValue store for run metadata (e.g., user session details).

(undo: () => Promise<void>) => void

Function used to register a compensating action executed if a later tool call in the same batch fails.

Schema Serialization

kenpachi includes a universal Zod schema serializer serializeZodSchema(schema: z.ZodTypeAny) that transforms any Zod definition into a standard JSON Schema object (type: "object", properties, required), automatically stripping non-standard fields (like $schema) for LLM provider compliance:

import { serializeZodSchema } from "kenpachi";
import { z } from "zod";

const jsonSchema = serializeZodSchema(
  z.object({
    city: z.string(),
    forecastDays: z.number(),
  })
);
// Output: { type: "object", properties: { city: { type: "string" }, forecastDays: { type: "number" } }, required: ["city", "forecastDays"] }

Getting Started

Core Concepts

API Reference

Parameters

ToolContext Parameter

Schema Serialization

​Parameters

​ToolContext Parameter

​Schema Serialization

Parameters

ToolContext Parameter

Schema Serialization