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