Open History to see the last commit
1---
2id: ToolDefinitionInstance
3title: ToolDefinitionInstance
4---
5
6# Interface: ToolDefinitionInstance\<TInput, TOutput, TName\>
7
8Defined in: [packages/typescript/ai/src/activities/chat/tools/tool-definition.ts:50](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L50)
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) = [`SchemaInput`](../type-aliases/SchemaInput.md)
25
26### TOutput
27
28`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
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: [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)
43
44***
45
46### description
47
48```ts
49description: string;
50```
51
52Defined in: [packages/typescript/ai/src/types.ts:509](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L509)
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, context?) => any;
75```
76
77Defined in: [packages/typescript/ai/src/types.ts:589](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L589)
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##### context?
95
96[`ToolExecutionContext`](ToolExecutionContext.md)
97
98#### Returns
99
100`any`
101
102Result to send back to the model (validated against outputSchema if provided)
103
104#### Example
105
106```ts
107execute: async (args) => {
108 const weather = await fetchWeather(args.location);
109 return weather; // Can return object or string
110}
111```
112
113#### Inherited from
114
115[`Tool`](Tool.md).[`execute`](Tool.md#execute)
116
117***
118
119### inputSchema?
120
121```ts
122optional inputSchema: TInput;
123```
124
125Defined in: [packages/typescript/ai/src/types.ts:549](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L549)
126
127Schema describing the tool's input parameters.
128
129Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
130Defines the structure and types of arguments the tool accepts.
131The model will generate arguments matching this schema.
132Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
133
134#### See
135
136 - https://standardschema.dev/json-schema
137 - https://json-schema.org/
138
139#### Examples
140
141```ts
142// Using Zod v4+ schema (natively supports Standard JSON Schema)
143import { z } from 'zod';
144z.object({
145 location: z.string().describe("City name or coordinates"),
146 unit: z.enum(["celsius", "fahrenheit"]).optional()
147})
148```
149
150```ts
151// Using ArkType (natively supports Standard JSON Schema)
152import { type } from 'arktype';
153type({
154 location: 'string',
155 unit: "'celsius' | 'fahrenheit'"
156})
157```
158
159```ts
160// Using plain JSON Schema
161{
162 type: 'object',
163 properties: {
164 location: { type: 'string', description: 'City name or coordinates' },
165 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
166 },
167 required: ['location']
168}
169```
170
171#### Inherited from
172
173[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
174
175***
176
177### lazy?
178
179```ts
180optional lazy: boolean;
181```
182
183Defined in: [packages/typescript/ai/src/types.ts:597](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L597)
184
185If 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().
186
187#### Inherited from
188
189[`Tool`](Tool.md).[`lazy`](Tool.md#lazy)
190
191***
192
193### metadata?
194
195```ts
196optional metadata: Record<string, any>;
197```
198
199Defined in: [packages/typescript/ai/src/types.ts:600](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L600)
200
201Additional metadata for adapters or custom extensions
202
203#### Inherited from
204
205[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
206
207***
208
209### name
210
211```ts
212name: TName;
213```
214
215Defined in: [packages/typescript/ai/src/types.ts:499](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L499)
216
217Unique name of the tool (used by the model to call it).
218
219Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
220Must be unique within the tools array.
221
222#### Example
223
224```ts
225"get_weather", "search_database", "sendEmail"
226```
227
228#### Inherited from
229
230[`Tool`](Tool.md).[`name`](Tool.md#name)
231
232***
233
234### needsApproval?
235
236```ts
237optional needsApproval: boolean;
238```
239
240Defined in: [packages/typescript/ai/src/types.ts:594](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L594)
241
242If true, tool execution requires user approval before running. Works with both server and client tools.
243
244#### Inherited from
245
246[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
247
248***
249
250### outputSchema?
251
252```ts
253optional outputSchema: TOutput;
254```
255
256Defined in: [packages/typescript/ai/src/types.ts:570](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L570)
257
258Optional schema for validating tool output.
259
260Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
261If provided with a Standard Schema compliant schema, tool results will be validated
262against this schema before being sent back to the model. This catches bugs in tool
263implementations and ensures consistent output formatting.
264
265Note: This is client-side validation only - not sent to LLM providers.
266Note: Plain JSON Schema output validation is not performed at runtime.
267
268#### Example
269
270```ts
271// Using Zod
272z.object({
273 temperature: z.number(),
274 conditions: z.string(),
275 forecast: z.array(z.string()).optional()
276})
277```
278
279#### Inherited from
280
281[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)