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