> ## Documentation Index
> Fetch the complete documentation index at: https://kenpachi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# defineTool

> API reference for defining typed, validated tools.

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

```typescript theme={null}
import { defineTool } from "kenpachi";
```

***

## Parameters

<ParamField path="definition" type="ToolDefinition" required>
  Configuration object describing tool behavior:

  <Expandable title="ToolDefinition Properties">
    <ResponseField name="name" type="string" required>
      The tool name passed to the model (must contain alphanumeric characters or underscores).
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Clear description telling the LLM when and how to use the tool.
    </ResponseField>

    <ResponseField name="schema" type="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`.
    </ResponseField>

    <ResponseField name="execute" type="(args: Args, ctx: ToolContext) => Promise<Result>" required>
      Async function executing tool logic with validated arguments.
    </ResponseField>

    <ResponseField name="repairable" type="boolean" default="true">
      Whether `kenpachi` should attempt argument repair and retry on schema validation failures.
    </ResponseField>
  </Expandable>
</ParamField>

***

## ToolContext Parameter

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

<ResponseField name="metadata" type="Record<string, unknown>">
  KeyValue store for run metadata (e.g., user session details).
</ResponseField>

<ResponseField name="registerCompensation" type="(undo: () => Promise<void>) => void">
  Function used to register a compensating action executed if a later tool call in the same batch fails.
</ResponseField>

***

## 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:

```typescript theme={null}
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"] }
```