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