Open History to see the last commit
1---
2id: ToolDefinition
3title: ToolDefinition
4---
5
6# Interface: ToolDefinition\<TInput, TOutput, TName\>
7
8Defined in: [activities/chat/tools/tool-definition.ts:104](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L104)
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) = `z.ZodType`
21
22### TOutput
23
24`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
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: [activities/chat/tools/tool-definition.ts:48](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L48)
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: [activities/chat/tools/tool-definition.ts:121](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L121)
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: [types.ts:340](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L340)
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) => any;
99```
100
101Defined in: [types.ts:411](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L411)
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#### Returns
119
120`any`
121
122Result to send back to the model (validated against outputSchema if provided)
123
124#### Example
125
126```ts
127execute: async (args) => {
128 const weather = await fetchWeather(args.location);
129 return weather; // Can return object or string
130}
131```
132
133#### Inherited from
134
135[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`execute`](ToolDefinitionInstance.md#execute)
136
137***
138
139### inputSchema?
140
141```ts
142optional inputSchema: TInput;
143```
144
145Defined in: [types.ts:372](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L372)
146
147Schema describing the tool's input parameters.
148
149Can be either a Zod schema or a JSON Schema object.
150Defines the structure and types of arguments the tool accepts.
151The model will generate arguments matching this schema.
152Zod schemas are converted to JSON Schema for LLM providers.
153
154#### See
155
156 - https://zod.dev/
157 - https://json-schema.org/
158
159#### Examples
160
161```ts
162// Using Zod schema
163import { z } from 'zod';
164z.object({
165 location: z.string().describe("City name or coordinates"),
166 unit: z.enum(["celsius", "fahrenheit"]).optional()
167})
168```
169
170```ts
171// Using JSON Schema
172{
173 type: 'object',
174 properties: {
175 location: { type: 'string', description: 'City name or coordinates' },
176 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
177 },
178 required: ['location']
179}
180```
181
182#### Inherited from
183
184[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`inputSchema`](ToolDefinitionInstance.md#inputschema)
185
186***
187
188### metadata?
189
190```ts
191optional metadata: Record<string, any>;
192```
193
194Defined in: [types.ts:417](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L417)
195
196Additional metadata for adapters or custom extensions
197
198#### Inherited from
199
200[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`metadata`](ToolDefinitionInstance.md#metadata)
201
202***
203
204### name
205
206```ts
207name: TName;
208```
209
210Defined in: [types.ts:330](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L330)
211
212Unique name of the tool (used by the model to call it).
213
214Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
215Must be unique within the tools array.
216
217#### Example
218
219```ts
220"get_weather", "search_database", "sendEmail"
221```
222
223#### Inherited from
224
225[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`name`](ToolDefinitionInstance.md#name)
226
227***
228
229### needsApproval?
230
231```ts
232optional needsApproval: boolean;
233```
234
235Defined in: [types.ts:414](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L414)
236
237If true, tool execution requires user approval before running. Works with both server and client tools.
238
239#### Inherited from
240
241[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`needsApproval`](ToolDefinitionInstance.md#needsapproval)
242
243***
244
245### outputSchema?
246
247```ts
248optional outputSchema: TOutput;
249```
250
251Defined in: [types.ts:392](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L392)
252
253Optional schema for validating tool output.
254
255Can be either a Zod schema or a JSON Schema object.
256If provided with a Zod schema, tool results will be validated against this schema before
257being sent back to the model. This catches bugs in tool implementations
258and ensures consistent output formatting.
259
260Note: This is client-side validation only - not sent to LLM providers.
261Note: JSON Schema output validation is not performed at runtime.
262
263#### Example
264
265```ts
266z.object({
267 temperature: z.number(),
268 conditions: z.string(),
269 forecast: z.array(z.string()).optional()
270})
271```
272
273#### Inherited from
274
275[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`outputSchema`](ToolDefinitionInstance.md#outputschema)
276
277***
278
279### server()
280
281```ts
282server: (execute) => ServerTool<TInput, TOutput, TName>;
283```
284
285Defined in: [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)
286
287Create a server-side tool with execute function
288
289#### Parameters
290
291##### execute
292
293(`args`) =>
294 \| [`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>
295 \| `Promise`\<[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>\>
296
297#### Returns
298
299[`ServerTool`](ServerTool.md)\<`TInput`, `TOutput`, `TName`\>