Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

Tool.md

249 lines6.1 KB

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
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
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']
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```