defineTool

Call Signature

function defineTool<TInSchema, TOutSchema, THandlerIn, THandlerOut>(spec, options?): Result<DefinedTool<TInSchema, TOutSchema, THandlerIn, THandlerOut>, ToolError>;

Build a validated Tool from a user-supplied definition.

Two authoring surfaces coexist:

1. JSON Schema Draft 2020-12 objects — the only shape that crosses the wire. Non-TS consumers use this.
2. Zod v4 schemas — TS-user sugar. Framework detects at author time, converts via z.toJSONSchema(), caches the JSON Schema wire form on tool.input / tool.output, preserves the original Zod schema on tool.inputZod / tool.outputZod for static type inference.

Verifies (fail-fast):

1. The manifest projection conforms to @kindgi/specs/tool.schema.json.
2. Every declared effects[].kind is in the closed EFFECT_KINDS set.
3. input and output are legal JSON Schema Draft 2020-12 documents (after Zod conversion, when applicable).

The handler is not validated at author time — its input/output are enforced by invokeTool at each call. Returning a tool from this function is the runtime's promise that it's structurally safe to invoke.

zod is a peer dependency. Workspaces that never author with Zod never install it and never pay any resolution cost. Callers that DO pass a Zod schema without zod installed get a clean invalid-schema error surfaced through the returned Result.

Type Parameters

Type Parameter	Default type
TInSchema extends AnySchema	-
TOutSchema extends AnySchema	-
THandlerIn	InferOutput<TInSchema>
THandlerOut	InferOutput<TOutSchema>

Parameters

Parameter	Type
spec	DefineToolSpec<TInSchema, TOutSchema, THandlerIn, THandlerOut>
options?	DefineToolOptions

Returns

Result<DefinedTool<TInSchema, TOutSchema, THandlerIn, THandlerOut>, ToolError>

Call Signature

function defineTool<TInput, TOutput>(spec, options?): Result<Tool<TInput, TOutput>, ToolError>;

Overload with explicit data-type generics, for JSON-Schema-only authors who want to state <TInput, TOutput> themselves. Without the generics, inference derives the handler types from a Zod schema, or (for JSON Schema) from the handler literal's return type.

Type Parameters

Type Parameter	Default type
TInput	unknown
TOutput	unknown

Parameters

Parameter	Type
spec	Tool<TInput, TOutput>
options?	DefineToolOptions

Returns

Result<Tool<TInput, TOutput>, ToolError>