Open History to see the last commit
1---
2id: toolDefinition
3title: toolDefinition
4---
5
6# Function: toolDefinition()
7
8```ts
9function toolDefinition<
10 TInput,
11 TOutput,
12 TName,
13 TNeedsApproval,
14 TApprovalSchema,
15>(config): ToolDefinition<
16 TInput,
17 TOutput,
18 TName,
19 TNeedsApproval,
20 TApprovalSchema
21>
22```
23
24Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:209](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L209)
25
26Create an isomorphic tool definition that can be used directly or instantiated for server/client
27
28The definition contains all tool metadata (name, description, schemas) and can be:
291. Used directly in chat() on the server (as a tool definition without execute)
302. Instantiated as a server tool with .server()
313. Instantiated as a client tool with .client()
32
33Supports any Standard JSON Schema compliant library (Zod v4+, ArkType, Valibot, etc.)
34or plain JSON Schema objects.
35
36## Conditional approval schema
37
38`approvalSchema` is available only when `needsApproval: true`. It accepts either
39one Standard Schema/JSON Schema for both decisions or a nonempty branch map:
40
41```ts
42type ApprovalSchemaConfig =
43 | SchemaInput
44 | { approve: SchemaInput; reject?: SchemaInput }
45 | { approve?: SchemaInput; reject: SchemaInput }
46```
47
48The schema generic is preserved by `.server()` and `.client()`. Client
49`tool-approval` interrupts infer the selected branch payload, require it when
50the schema requires it, and place it under `payload`. Approval may also carry an
51optional, fully validated `editedArgs` replacement when the tool has an input
52schema. Rejection never accepts edited arguments.
53
54Plain JSON Schema remains runtime-only and therefore produces `unknown` payload
55data. Standard Schema inputs such as Zod infer both runtime validation and the
56bound resolver overloads.
57
58At runtime, defining `approvalSchema` without `needsApproval: true` throws.
59TanStack AI converts the input, output, and selected approval branches to
60canonical JSON Schema, embeds their hashes in the protected interrupt binding,
61and validates again on resume. See [Interrupts](../../interrupts/overview) for the
62full lifecycle.
63
64## Type Parameters
65
66### TInput
67
68`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
69
70### TOutput
71
72`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
73
74### TName
75
76`TName` *extends* `string` = `string`
77
78### TNeedsApproval
79
80`TNeedsApproval` *extends* `boolean` = `false`. The literal `true` enables the
81approval capability in mapped client interrupt types.
82
83### TApprovalSchema
84
85`TApprovalSchema` *extends* `ApprovalSchemaConfig | undefined` = `undefined`.
86This generic is conditionally permitted only when `TNeedsApproval` is `true`.
87
88## Parameters
89
90### config
91
92[`ToolDefinitionConfig`](../interfaces/ToolDefinitionConfig.md)\<`TInput`, `TOutput`, `TName`, `TNeedsApproval`\>
93
94## Returns
95
96[`ToolDefinition`](../interfaces/ToolDefinition.md)\<`TInput`, `TOutput`, `TName`, `TNeedsApproval`\>
97
98## Example
99
100```typescript
101import { toolDefinition } from '@tanstack/ai';
102import { z } from 'zod';
103
104// Using Zod (natively supports Standard JSON Schema)
105const addToCartTool = toolDefinition({
106 name: 'addToCart',
107 description: 'Add a guitar to the shopping cart (requires approval)',
108 needsApproval: true,
109 inputSchema: z.object({
110 guitarId: z.string(),
111 quantity: z.number(),
112 }),
113 outputSchema: z.object({
114 success: z.boolean(),
115 cartId: z.string(),
116 totalItems: z.number(),
117 }),
118 approvalSchema: {
119 approve: z.object({ note: z.string() }),
120 reject: z.object({ reason: z.string() }),
121 },
122});
123
124// Use directly in chat (server-side, no execute function)
125chat({
126 tools: [addToCartTool],
127 // ...
128});
129
130// Or create server-side implementation
131const addToCartServer = addToCartTool.server(async (args) => {
132 // args is typed as { guitarId: string; quantity: number }
133 return {
134 success: true,
135 cartId: 'CART_' + Date.now(),
136 totalItems: args.quantity,
137 };
138});
139
140// Or create client-side implementation
141const addToCartClient = addToCartTool.client(async (args) => {
142 // Client-specific logic (e.g., localStorage)
143 return { success: true, cartId: 'local', totalItems: 1 };
144});
145```
146
147With `tools: [addToCartTool] as const`, the corresponding bound approval has
148branch-specific overloads:
149
150```ts
151interrupt.resolveInterrupt(true, {
152 editedArgs: { guitarId: 'guitar-2', quantity: 2 },
153 payload: { note: 'Reviewed' },
154})
155
156interrupt.resolveInterrupt(false, {
157 payload: { reason: 'Budget limit' },
158})
159```