Open History to see the last commit
1---
2id: Tool
3title: Tool
4---
5
6# Interface: Tool\<TInput, TOutput, TName\>
7
8Defined in: [packages/typescript/ai/src/types.ts:486](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L486)
9
10Tool/Function definition for function calling.
11
12Tools allow the model to interact with external systems, APIs, or perform computations.
13The model will decide when to call tools based on the user's request and the tool descriptions.
14
15Tools can use any Standard JSON Schema compliant library (Zod, ArkType, Valibot, etc.)
16or plain JSON Schema objects for runtime validation and type safety.
17
18## See
19
20 - https://platform.openai.com/docs/guides/function-calling
21 - https://docs.anthropic.com/claude/docs/tool-use
22 - https://standardschema.dev/json-schema
23
24## Extended by
25
26- [`ToolDefinitionInstance`](ToolDefinitionInstance.md)
27- [`ServerTool`](ServerTool.md)
28- [`ProviderTool`](ProviderTool.md)
29
30## Type Parameters
31
32### TInput
33
34`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
35
36### TOutput
37
38`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
39
40### TName
41
42`TName` *extends* `string` = `string`
43
44## Properties
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***
66
67### execute()?
68
69```ts
70optional execute: (args, context?) => any;
71```
72
73Defined in: [packages/typescript/ai/src/types.ts:589](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L589)
74
75Optional function to execute when the model calls this tool.
76
77If provided, the SDK will automatically execute the function with the model's arguments
78and feed the result back to the model. This enables autonomous tool use loops.
79
80Can return any value - will be automatically stringified if needed.
81
82#### Parameters
83
84##### args
85
86`any`
87
88The arguments parsed from the model's tool call (validated against inputSchema)
89
90##### context?
91
92[`ToolExecutionContext`](ToolExecutionContext.md)
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***
110
111### inputSchema?
112
113```ts
114optional inputSchema: TInput;
115```
116
117Defined in: [packages/typescript/ai/src/types.ts:549](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L549)
118
119Schema describing the tool's input parameters.
120
121Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
122Defines the structure and types of arguments the tool accepts.
123The model will generate arguments matching this schema.
124Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
125
126#### See
127
128 - https://standardschema.dev/json-schema
129 - https://json-schema.org/
130
131#### Examples
132
133```ts
134// Using Zod v4+ schema (natively supports Standard JSON Schema)
135import { z } from 'zod';
136z.object({
137 location: z.string().describe("City name or coordinates"),
138 unit: z.enum(["celsius", "fahrenheit"]).optional()
139})
140```
141
142```ts
143// Using ArkType (natively supports Standard JSON Schema)
144import { type } from 'arktype';
145type({
146 location: 'string',
147 unit: "'celsius' | 'fahrenheit'"
148})
149```
150
151```ts
152// Using plain JSON Schema
153{
154 type: 'object',
155 properties: {
156 location: { type: 'string', description: 'City name or coordinates' },
157 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
158 },
159 required: ['location']
160}
161```
162
163***
164
165### lazy?
166
167```ts
168optional lazy: boolean;
169```
170
171Defined in: [packages/typescript/ai/src/types.ts:597](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L597)
172
173If 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().
174
175***
176
177### metadata?
178
179```ts
180optional metadata: Record<string, any>;
181```
182
183Defined in: [packages/typescript/ai/src/types.ts:600](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L600)
184
185Additional metadata for adapters or custom extensions
186
187***
188
189### name
190
191```ts
192name: TName;
193```
194
195Defined in: [packages/typescript/ai/src/types.ts:499](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L499)
196
197Unique name of the tool (used by the model to call it).
198
199Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
200Must be unique within the tools array.
201
202#### Example
203
204```ts
205"get_weather", "search_database", "sendEmail"
206```
207
208***
209
210### needsApproval?
211
212```ts
213optional needsApproval: boolean;
214```
215
216Defined in: [packages/typescript/ai/src/types.ts:594](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L594)
217
218If true, tool execution requires user approval before running. Works with both server and client tools.
219
220***
221
222### outputSchema?
223
224```ts
225optional outputSchema: TOutput;
226```
227
228Defined in: [packages/typescript/ai/src/types.ts:570](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L570)
229
230Optional schema for validating tool output.
231
232Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
233If provided with a Standard Schema compliant schema, tool results will be validated
234against this schema before being sent back to the model. This catches bugs in tool
235implementations and ensures consistent output formatting.
236
237Note: This is client-side validation only - not sent to LLM providers.
238Note: Plain JSON Schema output validation is not performed at runtime.
239
240#### Example
241
242```ts
243// Using Zod
244z.object({
245 temperature: z.number(),
246 conditions: z.string(),
247 forecast: z.array(z.string()).optional()
248})
249```