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

ToolDefinitionInstance.md

251 lines5.3 KB

1---
2id: ToolDefinitionInstance
3title: ToolDefinitionInstance
4---
5​
6# Interface: ToolDefinitionInstance\<TInput, TOutput, TName\>
7​
8Defined in: [activities/chat/tools/tool-definition.ts:43](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L43)
9​
10Tool definition that can be used directly or instantiated for server/client
11​
12## Extends
13​
14- [`Tool`](Tool.md)\<`TInput`, `TOutput`, `TName`\>
15​
16## Extended by
17​
18- [`ToolDefinition`](ToolDefinition.md)
19​
20## Type Parameters
21​
22### TInput
23​
24`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
25​
26### TOutput
27​
28`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
29​
30### TName
31​
32`TName` *extends* `string` = `string`
33​
34## Properties
35​
36### \_\_toolSide
37​
38```ts
39__toolSide: "definition";
40```
41​
42Defined in: [activities/chat/tools/tool-definition.ts:48](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L48)
43​
44***
45​
46### description
47​
48```ts
49description: string;
50```
51​
52Defined in: [types.ts:340](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L340)
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#### Inherited from
66​
67[`Tool`](Tool.md).[`description`](Tool.md#description)
68​
69***
70​
71### execute()?
72​
73```ts
74optional execute: (args) => any;
75```
76​
77Defined in: [types.ts:411](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L411)
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#### Parameters
87​
88##### args
89​
90`any`
91​
92The arguments parsed from the model's tool call (validated against inputSchema)
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#### Inherited from
110​
111[`Tool`](Tool.md).[`execute`](Tool.md#execute)
112​
113***
114​
115### inputSchema?
116​
117```ts
118optional inputSchema: TInput;
119```
120​
121Defined in: [types.ts:372](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L372)
122​
123Schema describing the tool's input parameters.
124​
125Can be either a Zod schema or a JSON Schema object.
126Defines the structure and types of arguments the tool accepts.
127The model will generate arguments matching this schema.
128Zod schemas are converted to JSON Schema for LLM providers.
129​
130#### See
131​
132 - https://zod.dev/
133 - https://json-schema.org/
134​
135#### Examples
136​
137```ts
138// Using Zod schema
139import { z } from 'zod';
140z.object({
141 location: z.string().describe("City name or coordinates"),
142 unit: z.enum(["celsius", "fahrenheit"]).optional()
143})
144```
145​
146```ts
147// Using JSON Schema
149 type: 'object',
150 properties: {
151 location: { type: 'string', description: 'City name or coordinates' },
152 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
153 },
154 required: ['location']
156```
157​
158#### Inherited from
159​
160[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
161​
162***
163​
164### metadata?
165​
166```ts
167optional metadata: Record<string, any>;
168```
169​
170Defined in: [types.ts:417](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L417)
171​
172Additional metadata for adapters or custom extensions
173​
174#### Inherited from
175​
176[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
177​
178***
179​
180### name
181​
182```ts
183name: TName;
184```
185​
186Defined in: [types.ts:330](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L330)
187​
188Unique name of the tool (used by the model to call it).
189​
190Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
191Must be unique within the tools array.
192​
193#### Example
194​
195```ts
196"get_weather", "search_database", "sendEmail"
197```
198​
199#### Inherited from
200​
201[`Tool`](Tool.md).[`name`](Tool.md#name)
202​
203***
204​
205### needsApproval?
206​
207```ts
208optional needsApproval: boolean;
209```
210​
211Defined in: [types.ts:414](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L414)
212​
213If true, tool execution requires user approval before running. Works with both server and client tools.
214​
215#### Inherited from
216​
217[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
218​
219***
220​
221### outputSchema?
222​
223```ts
224optional outputSchema: TOutput;
225```
226​
227Defined in: [types.ts:392](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L392)
228​
229Optional schema for validating tool output.
230​
231Can be either a Zod schema or a JSON Schema object.
232If provided with a Zod schema, tool results will be validated against this schema before
233being sent back to the model. This catches bugs in tool implementations
234and ensures consistent output formatting.
235​
236Note: This is client-side validation only - not sent to LLM providers.
237Note: JSON Schema output validation is not performed at runtime.
238​
239#### Example
240​
241```ts
242z.object({
243 temperature: z.number(),
244 conditions: z.string(),
245 forecast: z.array(z.string()).optional()
246})
247```
248​
249#### Inherited from
250​
251[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)