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

Tool.md

220 lines4.9 KB

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