Open History to see the last commit
1---
2id: ToolDefinition
3title: ToolDefinition
4---
5
6# Interface: ToolDefinition\<TInput, TOutput, TName, TNeedsApproval\>
7
8Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:125](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L125)
9
10Tool definition builder that allows creating server or client tools from a shared definition
11
12## Extends
13
14- [`ToolDefinitionInstance`](ToolDefinitionInstance.md)\<`TInput`, `TOutput`, `TName`, `unknown`, `TNeedsApproval`\>
15
16## Type Parameters
17
18### TInput
19
20`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
21
22### TOutput
23
24`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
25
26### TName
27
28`TName` *extends* `string` = `string`
29
30### TNeedsApproval
31
32`TNeedsApproval` *extends* `boolean` = `false`
33
34## Properties
35
36### \_\_toolSide
37
38```ts
39__toolSide: "definition";
40```
41
42Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:60](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L60)
43
44#### Inherited from
45
46[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`__toolSide`](ToolDefinitionInstance.md#__toolside)
47
48***
49
50### client()
51
52```ts
53client: <TContext>(execute?) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval>;
54```
55
56Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:149](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L149)
57
58Create a client-side tool with optional execute function.
59Carries the definition's `needsApproval` literal through to the client
60tool so the tool-call part's `approval` field stays gated on it.
61
62#### Type Parameters
63
64##### TContext
65
66`TContext` = `unknown`
67
68#### Parameters
69
70##### execute?
71
72[`ToolExecuteFunction`](../type-aliases/ToolExecuteFunction.md)\<`TInput`, `TOutput`, `TContext`\>
73
74#### Returns
75
76[`ClientTool`](ClientTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`, `TNeedsApproval`\>
77
78***
79
80### description
81
82```ts
83description: string;
84```
85
86Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622)
87
88Clear description of what the tool does.
89
90This is crucial - the model uses this to decide when to call the tool.
91Be specific about what the tool does, what parameters it needs, and what it returns.
92
93#### Example
94
95```ts
96"Get the current weather in a given location. Returns temperature, conditions, and forecast."
97```
98
99#### Inherited from
100
101[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`description`](ToolDefinitionInstance.md#description)
102
103***
104
105### execute()?
106
107```ts
108optional execute: (args, context?) =>
109 | InferSchemaType<TOutput>
110| Promise<InferSchemaType<TOutput>>;
111```
112
113Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702)
114
115Optional function to execute when the model calls this tool.
116
117If provided, the SDK will automatically execute the function with the model's arguments
118and feed the result back to the model. This enables autonomous tool use loops.
119
120Can return any value - will be automatically stringified if needed.
121
122#### Parameters
123
124##### args
125
126[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TInput`\>
127
128The arguments parsed from the model's tool call (validated against inputSchema)
129
130##### context?
131
132[`ToolExecutionContext`](../type-aliases/ToolExecutionContext.md)\<`unknown`\>
133
134#### Returns
135
136 \| [`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>
137 \| `Promise`\<[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>\>
138
139Result to send back to the model (validated against outputSchema if provided)
140
141#### Example
142
143```ts
144execute: async (args) => {
145 const weather = await fetchWeather(args.location);
146 return weather; // Can return object or string
147}
148```
149
150#### Inherited from
151
152[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`execute`](ToolDefinitionInstance.md#execute)
153
154***
155
156### inputSchema?
157
158```ts
159optional inputSchema: TInput;
160```
161
162Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662)
163
164Schema describing the tool's input parameters.
165
166Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
167Defines the structure and types of arguments the tool accepts.
168The model will generate arguments matching this schema.
169Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
170
171#### See
172
173 - https://standardschema.dev/json-schema
174 - https://json-schema.org/
175
176#### Examples
177
178```ts
179// Using Zod v4+ schema (natively supports Standard JSON Schema)
180import { z } from 'zod';
181z.object({
182 location: z.string().describe("City name or coordinates"),
183 unit: z.enum(["celsius", "fahrenheit"]).optional()
184})
185```
186
187```ts
188// Using ArkType (natively supports Standard JSON Schema)
189import { type } from 'arktype';
190type({
191 location: 'string',
192 unit: "'celsius' | 'fahrenheit'"
193})
194```
195
196```ts
197// Using plain JSON Schema
198{
199 type: 'object',
200 properties: {
201 location: { type: 'string', description: 'City name or coordinates' },
202 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
203 },
204 required: ['location']
205}
206```
207
208#### Inherited from
209
210[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`inputSchema`](ToolDefinitionInstance.md#inputschema)
211
212***
213
214### lazy?
215
216```ts
217optional lazy: boolean;
218```
219
220Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708)
221
222If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
223
224#### Inherited from
225
226[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`lazy`](ToolDefinitionInstance.md#lazy)
227
228***
229
230### metadata?
231
232```ts
233optional metadata: Record<string, any>;
234```
235
236Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711)
237
238Additional metadata for adapters or custom extensions
239
240#### Inherited from
241
242[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`metadata`](ToolDefinitionInstance.md#metadata)
243
244***
245
246### name
247
248```ts
249name: TName;
250```
251
252Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612)
253
254Unique name of the tool (used by the model to call it).
255
256Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
257Must be unique within the tools array.
258
259#### Example
260
261```ts
262"get_weather", "search_database", "sendEmail"
263```
264
265#### Inherited from
266
267[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`name`](ToolDefinitionInstance.md#name)
268
269***
270
271### needsApproval?
272
273```ts
274optional needsApproval: TNeedsApproval;
275```
276
277Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:63](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L63)
278
279If true, tool execution requires user approval before running. Works with both server and client tools.
280
281#### Inherited from
282
283[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`needsApproval`](ToolDefinitionInstance.md#needsapproval)
284
285***
286
287### outputSchema?
288
289```ts
290optional outputSchema: TOutput;
291```
292
293Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683)
294
295Optional schema for validating tool output.
296
297Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
298If provided with a Standard Schema compliant schema, tool results will be validated
299against this schema before being sent back to the model. This catches bugs in tool
300implementations and ensures consistent output formatting.
301
302Note: This is client-side validation only - not sent to LLM providers.
303Note: Plain JSON Schema output validation is not performed at runtime.
304
305#### Example
306
307```ts
308// Using Zod
309z.object({
310 temperature: z.number(),
311 conditions: z.string(),
312 forecast: z.array(z.string()).optional()
313})
314```
315
316#### Inherited from
317
318[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`outputSchema`](ToolDefinitionInstance.md#outputschema)
319
320***
321
322### server()
323
324```ts
325server: <TContext>(execute) => ServerTool<TInput, TOutput, TName, TContext>;
326```
327
328Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:140](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L140)
329
330Create a server-side tool with execute function
331
332#### Type Parameters
333
334##### TContext
335
336`TContext` = `unknown`
337
338#### Parameters
339
340##### execute
341
342[`ToolExecuteFunction`](../type-aliases/ToolExecuteFunction.md)\<`TInput`, `TOutput`, `TContext`\>
343
344#### Returns
345
346[`ServerTool`](ServerTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`\>