Open History to see the last commit
1---
2id: ToolDefinitionInstance
3title: ToolDefinitionInstance
4---
5
6# Interface: ToolDefinitionInstance\<TInput, TOutput, TName\>
7
8Defined in: [activities/chat/tools/tool-definition.ts:43](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L43)
9
10Tool definition that can be used directly or instantiated for server/client
11
12## Extends
13
14- [`Tool`](Tool.md)\<`TInput`, `TOutput`, `TName`\>
15
16## Extended by
17
18- [`ToolDefinition`](ToolDefinition.md)
19
20## Type Parameters
21
22### TInput
23
24`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
25
26### TOutput
27
28`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
29
30### TName
31
32`TName` *extends* `string` = `string`
33
34## Properties
35
36### \_\_toolSide
37
38```ts
39__toolSide: "definition";
40```
41
42Defined 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)
43
44***
45
46### description
47
48```ts
49description: string;
50```
51
52Defined in: [types.ts:340](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L340)
53
54Clear description of what the tool does.
55
56This is crucial - the model uses this to decide when to call the tool.
57Be specific about what the tool does, what parameters it needs, and what it returns.
58
59#### Example
60
61```ts
62"Get the current weather in a given location. Returns temperature, conditions, and forecast."
63```
64
65#### Inherited from
66
67[`Tool`](Tool.md).[`description`](Tool.md#description)
68
69***
70
71### execute()?
72
73```ts
74optional execute: (args) => any;
75```
76
77Defined in: [types.ts:411](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L411)
78
79Optional function to execute when the model calls this tool.
80
81If provided, the SDK will automatically execute the function with the model's arguments
82and feed the result back to the model. This enables autonomous tool use loops.
83
84Can return any value - will be automatically stringified if needed.
85
86#### Parameters
87
88##### args
89
90`any`
91
92The arguments parsed from the model's tool call (validated against inputSchema)
93
94#### Returns
95
96`any`
97
98Result to send back to the model (validated against outputSchema if provided)
99
100#### Example
101
102```ts
103execute: async (args) => {
104 const weather = await fetchWeather(args.location);
105 return weather; // Can return object or string
106}
107```
108
109#### Inherited from
110
111[`Tool`](Tool.md).[`execute`](Tool.md#execute)
112
113***
114
115### inputSchema?
116
117```ts
118optional inputSchema: TInput;
119```
120
121Defined in: [types.ts:372](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L372)
122
123Schema describing the tool's input parameters.
124
125Can be either a Zod schema or a JSON Schema object.
126Defines the structure and types of arguments the tool accepts.
127The model will generate arguments matching this schema.
128Zod schemas are converted to JSON Schema for LLM providers.
129
130#### See
131
132 - https://zod.dev/
133 - https://json-schema.org/
134
135#### Examples
136
137```ts
138// Using Zod schema
139import { z } from 'zod';
140z.object({
141 location: z.string().describe("City name or coordinates"),
142 unit: z.enum(["celsius", "fahrenheit"]).optional()
143})
144```
145
146```ts
147// Using JSON Schema
148{
149 type: 'object',
150 properties: {
151 location: { type: 'string', description: 'City name or coordinates' },
152 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
153 },
154 required: ['location']
155}
156```
157
158#### Inherited from
159
160[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
161
162***
163
164### metadata?
165
166```ts
167optional metadata: Record<string, any>;
168```
169
170Defined in: [types.ts:417](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L417)
171
172Additional metadata for adapters or custom extensions
173
174#### Inherited from
175
176[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
177
178***
179
180### name
181
182```ts
183name: TName;
184```
185
186Defined in: [types.ts:330](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L330)
187
188Unique name of the tool (used by the model to call it).
189
190Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
191Must be unique within the tools array.
192
193#### Example
194
195```ts
196"get_weather", "search_database", "sendEmail"
197```
198
199#### Inherited from
200
201[`Tool`](Tool.md).[`name`](Tool.md#name)
202
203***
204
205### needsApproval?
206
207```ts
208optional needsApproval: boolean;
209```
210
211Defined in: [types.ts:414](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L414)
212
213If true, tool execution requires user approval before running. Works with both server and client tools.
214
215#### Inherited from
216
217[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
218
219***
220
221### outputSchema?
222
223```ts
224optional outputSchema: TOutput;
225```
226
227Defined in: [types.ts:392](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L392)
228
229Optional schema for validating tool output.
230
231Can be either a Zod schema or a JSON Schema object.
232If provided with a Zod schema, tool results will be validated against this schema before
233being sent back to the model. This catches bugs in tool implementations
234and ensures consistent output formatting.
235
236Note: This is client-side validation only - not sent to LLM providers.
237Note: JSON Schema output validation is not performed at runtime.
238
239#### Example
240
241```ts
242z.object({
243 temperature: z.number(),
244 conditions: z.string(),
245 forecast: z.array(z.string()).optional()
246})
247```
248
249#### Inherited from
250
251[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)