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

ToolDefinition.md

299 lines7.0 KB

1---
2id: ToolDefinition
3title: ToolDefinition
4---
5​
6# Interface: ToolDefinition\<TInput, TOutput, TName\>
7​
8Defined in: [activities/chat/tools/tool-definition.ts:104](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L104)
9​
10Tool definition builder that allows creating server or client tools from a shared definition
11​
12## Extends
13​
14- [`ToolDefinitionInstance`](ToolDefinitionInstance.md)\<`TInput`, `TOutput`, `TName`\>
15​
16## Type Parameters
17​
18### TInput
19​
20`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
21​
22### TOutput
23​
24`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
25​
26### TName
27​
28`TName` *extends* `string` = `string`
29​
30## Properties
31​
32### \_\_toolSide
33​
34```ts
35__toolSide: "definition";
36```
37​
38Defined 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)
39​
40#### Inherited from
41​
42[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`__toolSide`](ToolDefinitionInstance.md#__toolside)
43​
44***
45​
46### client()
47​
48```ts
49client: (execute?) => ClientTool<TInput, TOutput, TName>;
50```
51​
52Defined in: [activities/chat/tools/tool-definition.ts:121](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L121)
53​
54Create a client-side tool with optional execute function
55​
56#### Parameters
57​
58##### execute?
59​
60(`args`) =>
61 \| [`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>
62 \| `Promise`\<[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>\>
63​
64#### Returns
65​
66[`ClientTool`](ClientTool.md)\<`TInput`, `TOutput`, `TName`\>
67​
68***
69​
70### description
71​
72```ts
73description: string;
74```
75​
76Defined in: [types.ts:340](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L340)
77​
78Clear description of what the tool does.
79​
80This is crucial - the model uses this to decide when to call the tool.
81Be specific about what the tool does, what parameters it needs, and what it returns.
82​
83#### Example
84​
85```ts
86"Get the current weather in a given location. Returns temperature, conditions, and forecast."
87```
88​
89#### Inherited from
90​
91[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`description`](ToolDefinitionInstance.md#description)
92​
93***
94​
95### execute()?
96​
97```ts
98optional execute: (args) => any;
99```
100​
101Defined in: [types.ts:411](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L411)
102​
103Optional function to execute when the model calls this tool.
104​
105If provided, the SDK will automatically execute the function with the model's arguments
106and feed the result back to the model. This enables autonomous tool use loops.
107​
108Can return any value - will be automatically stringified if needed.
109​
110#### Parameters
111​
112##### args
113​
114`any`
115​
116The arguments parsed from the model's tool call (validated against inputSchema)
117​
118#### Returns
119​
120`any`
121​
122Result to send back to the model (validated against outputSchema if provided)
123​
124#### Example
125​
126```ts
127execute: async (args) => {
128 const weather = await fetchWeather(args.location);
129 return weather; // Can return object or string
131```
132​
133#### Inherited from
134​
135[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`execute`](ToolDefinitionInstance.md#execute)
136​
137***
138​
139### inputSchema?
140​
141```ts
142optional inputSchema: TInput;
143```
144​
145Defined in: [types.ts:372](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L372)
146​
147Schema describing the tool's input parameters.
148​
149Can be either a Zod schema or a JSON Schema object.
150Defines the structure and types of arguments the tool accepts.
151The model will generate arguments matching this schema.
152Zod schemas are converted to JSON Schema for LLM providers.
153​
154#### See
155​
156 - https://zod.dev/
157 - https://json-schema.org/
158​
159#### Examples
160​
161```ts
162// Using Zod schema
163import { z } from 'zod';
164z.object({
165 location: z.string().describe("City name or coordinates"),
166 unit: z.enum(["celsius", "fahrenheit"]).optional()
167})
168```
169​
170```ts
171// Using JSON Schema
173 type: 'object',
174 properties: {
175 location: { type: 'string', description: 'City name or coordinates' },
176 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
177 },
178 required: ['location']
180```
181​
182#### Inherited from
183​
184[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`inputSchema`](ToolDefinitionInstance.md#inputschema)
185​
186***
187​
188### metadata?
189​
190```ts
191optional metadata: Record<string, any>;
192```
193​
194Defined in: [types.ts:417](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L417)
195​
196Additional metadata for adapters or custom extensions
197​
198#### Inherited from
199​
200[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`metadata`](ToolDefinitionInstance.md#metadata)
201​
202***
203​
204### name
205​
206```ts
207name: TName;
208```
209​
210Defined in: [types.ts:330](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L330)
211​
212Unique name of the tool (used by the model to call it).
213​
214Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
215Must be unique within the tools array.
216​
217#### Example
218​
219```ts
220"get_weather", "search_database", "sendEmail"
221```
222​
223#### Inherited from
224​
225[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`name`](ToolDefinitionInstance.md#name)
226​
227***
228​
229### needsApproval?
230​
231```ts
232optional needsApproval: boolean;
233```
234​
235Defined in: [types.ts:414](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L414)
236​
237If true, tool execution requires user approval before running. Works with both server and client tools.
238​
239#### Inherited from
240​
241[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`needsApproval`](ToolDefinitionInstance.md#needsapproval)
242​
243***
244​
245### outputSchema?
246​
247```ts
248optional outputSchema: TOutput;
249```
250​
251Defined in: [types.ts:392](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L392)
252​
253Optional schema for validating tool output.
254​
255Can be either a Zod schema or a JSON Schema object.
256If provided with a Zod schema, tool results will be validated against this schema before
257being sent back to the model. This catches bugs in tool implementations
258and ensures consistent output formatting.
259​
260Note: This is client-side validation only - not sent to LLM providers.
261Note: JSON Schema output validation is not performed at runtime.
262​
263#### Example
264​
265```ts
266z.object({
267 temperature: z.number(),
268 conditions: z.string(),
269 forecast: z.array(z.string()).optional()
270})
271```
272​
273#### Inherited from
274​
275[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`outputSchema`](ToolDefinitionInstance.md#outputschema)
276​
277***
278​
279### server()
280​
281```ts
282server: (execute) => ServerTool<TInput, TOutput, TName>;
283```
284​
285Defined in: [activities/chat/tools/tool-definition.ts:112](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L112)
286​
287Create a server-side tool with execute function
288​
289#### Parameters
290​
291##### execute
292​
293(`args`) =>
294 \| [`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>
295 \| `Promise`\<[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>\>
296​
297#### Returns
298​
299[`ServerTool`](ServerTool.md)\<`TInput`, `TOutput`, `TName`\>