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

Tool.md

243 lines5.9 KB

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