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

ToolDefinition.md

329 lines8.3 KB

1---
2id: ToolDefinition
3title: ToolDefinition
4---
5​
6# Interface: ToolDefinition\<TInput, TOutput, TName\>
7​
8Defined in: [packages/typescript/ai/src/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)
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) = [`SchemaInput`](../type-aliases/SchemaInput.md)
21​
22### TOutput
23​
24`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
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: [packages/typescript/ai/src/activities/chat/tools/tool-definition.ts:55](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L55)
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: [packages/typescript/ai/src/activities/chat/tools/tool-definition.ts:130](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L130)
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: [packages/typescript/ai/src/types.ts:509](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L509)
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, context?) => any;
99```
100​
101Defined in: [packages/typescript/ai/src/types.ts:589](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L589)
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##### context?
119​
120[`ToolExecutionContext`](ToolExecutionContext.md)
121​
122#### Returns
123​
124`any`
125​
126Result to send back to the model (validated against outputSchema if provided)
127​
128#### Example
129​
130```ts
131execute: async (args) => {
132 const weather = await fetchWeather(args.location);
133 return weather; // Can return object or string
135```
136​
137#### Inherited from
138​
139[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`execute`](ToolDefinitionInstance.md#execute)
140​
141***
142​
143### inputSchema?
144​
145```ts
146optional inputSchema: TInput;
147```
148​
149Defined in: [packages/typescript/ai/src/types.ts:549](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L549)
150​
151Schema describing the tool's input parameters.
152​
153Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
154Defines the structure and types of arguments the tool accepts.
155The model will generate arguments matching this schema.
156Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
157​
158#### See
159​
160 - https://standardschema.dev/json-schema
161 - https://json-schema.org/
162​
163#### Examples
164​
165```ts
166// Using Zod v4+ schema (natively supports Standard JSON Schema)
167import { z } from 'zod';
168z.object({
169 location: z.string().describe("City name or coordinates"),
170 unit: z.enum(["celsius", "fahrenheit"]).optional()
171})
172```
173​
174```ts
175// Using ArkType (natively supports Standard JSON Schema)
176import { type } from 'arktype';
177type({
178 location: 'string',
179 unit: "'celsius' | 'fahrenheit'"
180})
181```
182​
183```ts
184// Using plain JSON Schema
186 type: 'object',
187 properties: {
188 location: { type: 'string', description: 'City name or coordinates' },
189 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
190 },
191 required: ['location']
193```
194​
195#### Inherited from
196​
197[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`inputSchema`](ToolDefinitionInstance.md#inputschema)
198​
199***
200​
201### lazy?
202​
203```ts
204optional lazy: boolean;
205```
206​
207Defined in: [packages/typescript/ai/src/types.ts:597](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L597)
208​
209If 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().
210​
211#### Inherited from
212​
213[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`lazy`](ToolDefinitionInstance.md#lazy)
214​
215***
216​
217### metadata?
218​
219```ts
220optional metadata: Record<string, any>;
221```
222​
223Defined in: [packages/typescript/ai/src/types.ts:600](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L600)
224​
225Additional metadata for adapters or custom extensions
226​
227#### Inherited from
228​
229[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`metadata`](ToolDefinitionInstance.md#metadata)
230​
231***
232​
233### name
234​
235```ts
236name: TName;
237```
238​
239Defined in: [packages/typescript/ai/src/types.ts:499](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L499)
240​
241Unique name of the tool (used by the model to call it).
242​
243Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
244Must be unique within the tools array.
245​
246#### Example
247​
248```ts
249"get_weather", "search_database", "sendEmail"
250```
251​
252#### Inherited from
253​
254[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`name`](ToolDefinitionInstance.md#name)
255​
256***
257​
258### needsApproval?
259​
260```ts
261optional needsApproval: boolean;
262```
263​
264Defined in: [packages/typescript/ai/src/types.ts:594](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L594)
265​
266If true, tool execution requires user approval before running. Works with both server and client tools.
267​
268#### Inherited from
269​
270[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`needsApproval`](ToolDefinitionInstance.md#needsapproval)
271​
272***
273​
274### outputSchema?
275​
276```ts
277optional outputSchema: TOutput;
278```
279​
280Defined in: [packages/typescript/ai/src/types.ts:570](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L570)
281​
282Optional schema for validating tool output.
283​
284Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
285If provided with a Standard Schema compliant schema, tool results will be validated
286against this schema before being sent back to the model. This catches bugs in tool
287implementations and ensures consistent output formatting.
288​
289Note: This is client-side validation only - not sent to LLM providers.
290Note: Plain JSON Schema output validation is not performed at runtime.
291​
292#### Example
293​
294```ts
295// Using Zod
296z.object({
297 temperature: z.number(),
298 conditions: z.string(),
299 forecast: z.array(z.string()).optional()
300})
301```
302​
303#### Inherited from
304​
305[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`outputSchema`](ToolDefinitionInstance.md#outputschema)
306​
307***
308​
309### server()
310​
311```ts
312server: (execute) => ServerTool<TInput, TOutput, TName>;
313```
314​
315Defined in: [packages/typescript/ai/src/activities/chat/tools/tool-definition.ts:120](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L120)
316​
317Create a server-side tool with execute function
318​
319#### Parameters
320​
321##### execute
322​
323(`args`, `context?`) =>
324 \| [`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>
325 \| `Promise`\<[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>\>
326​
327#### Returns
328​
329[`ServerTool`](ServerTool.md)\<`TInput`, `TOutput`, `TName`\>