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

ToolDefinition.md

346 lines8.8 KB

1---
2id: ToolDefinition
3title: ToolDefinition
4---
5​
6# Interface: ToolDefinition\<TInput, TOutput, TName, TNeedsApproval\>
7​
8Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:125](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L125)
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`, `unknown`, `TNeedsApproval`\>
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### TNeedsApproval
31​
32`TNeedsApproval` *extends* `boolean` = `false`
33​
34## Properties
35​
36### \_\_toolSide
37​
38```ts
39__toolSide: "definition";
40```
41​
42Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:60](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L60)
43​
44#### Inherited from
45​
46[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`__toolSide`](ToolDefinitionInstance.md#__toolside)
47​
48***
49​
50### client()
51​
52```ts
53client: <TContext>(execute?) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval>;
54```
55​
56Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:149](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L149)
57​
58Create a client-side tool with optional execute function.
59Carries the definition's `needsApproval` literal through to the client
60tool so the tool-call part's `approval` field stays gated on it.
61​
62#### Type Parameters
63​
64##### TContext
65​
66`TContext` = `unknown`
67​
68#### Parameters
69​
70##### execute?
71​
72[`ToolExecuteFunction`](../type-aliases/ToolExecuteFunction.md)\<`TInput`, `TOutput`, `TContext`\>
73​
74#### Returns
75​
76[`ClientTool`](ClientTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`, `TNeedsApproval`\>
77​
78***
79​
80### description
81​
82```ts
83description: string;
84```
85​
86Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622)
87​
88Clear description of what the tool does.
89​
90This is crucial - the model uses this to decide when to call the tool.
91Be specific about what the tool does, what parameters it needs, and what it returns.
92​
93#### Example
94​
95```ts
96"Get the current weather in a given location. Returns temperature, conditions, and forecast."
97```
98​
99#### Inherited from
100​
101[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`description`](ToolDefinitionInstance.md#description)
102​
103***
104​
105### execute()?
106​
107```ts
108optional execute: (args, context?) =>
109 | InferSchemaType<TOutput>
110| Promise<InferSchemaType<TOutput>>;
111```
112​
113Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702)
114​
115Optional function to execute when the model calls this tool.
116​
117If provided, the SDK will automatically execute the function with the model's arguments
118and feed the result back to the model. This enables autonomous tool use loops.
119​
120Can return any value - will be automatically stringified if needed.
121​
122#### Parameters
123​
124##### args
125​
126[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TInput`\>
127​
128The arguments parsed from the model's tool call (validated against inputSchema)
129​
130##### context?
131​
132[`ToolExecutionContext`](../type-aliases/ToolExecutionContext.md)\<`unknown`\>
133​
134#### Returns
135​
136 \| [`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>
137 \| `Promise`\<[`InferSchemaType`](../type-aliases/InferSchemaType.md)\<`TOutput`\>\>
138​
139Result to send back to the model (validated against outputSchema if provided)
140​
141#### Example
142​
143```ts
144execute: async (args) => {
145 const weather = await fetchWeather(args.location);
146 return weather; // Can return object or string
148```
149​
150#### Inherited from
151​
152[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`execute`](ToolDefinitionInstance.md#execute)
153​
154***
155​
156### inputSchema?
157​
158```ts
159optional inputSchema: TInput;
160```
161​
162Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662)
163​
164Schema describing the tool's input parameters.
165​
166Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
167Defines the structure and types of arguments the tool accepts.
168The model will generate arguments matching this schema.
169Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
170​
171#### See
172​
173 - https://standardschema.dev/json-schema
174 - https://json-schema.org/
175​
176#### Examples
177​
178```ts
179// Using Zod v4+ schema (natively supports Standard JSON Schema)
180import { z } from 'zod';
181z.object({
182 location: z.string().describe("City name or coordinates"),
183 unit: z.enum(["celsius", "fahrenheit"]).optional()
184})
185```
186​
187```ts
188// Using ArkType (natively supports Standard JSON Schema)
189import { type } from 'arktype';
190type({
191 location: 'string',
192 unit: "'celsius' | 'fahrenheit'"
193})
194```
195​
196```ts
197// Using plain JSON Schema
199 type: 'object',
200 properties: {
201 location: { type: 'string', description: 'City name or coordinates' },
202 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
203 },
204 required: ['location']
206```
207​
208#### Inherited from
209​
210[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`inputSchema`](ToolDefinitionInstance.md#inputschema)
211​
212***
213​
214### lazy?
215​
216```ts
217optional lazy: boolean;
218```
219​
220Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708)
221​
222If 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).
223​
224#### Inherited from
225​
226[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`lazy`](ToolDefinitionInstance.md#lazy)
227​
228***
229​
230### metadata?
231​
232```ts
233optional metadata: Record<string, any>;
234```
235​
236Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711)
237​
238Additional metadata for adapters or custom extensions
239​
240#### Inherited from
241​
242[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`metadata`](ToolDefinitionInstance.md#metadata)
243​
244***
245​
246### name
247​
248```ts
249name: TName;
250```
251​
252Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612)
253​
254Unique name of the tool (used by the model to call it).
255​
256Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
257Must be unique within the tools array.
258​
259#### Example
260​
261```ts
262"get_weather", "search_database", "sendEmail"
263```
264​
265#### Inherited from
266​
267[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`name`](ToolDefinitionInstance.md#name)
268​
269***
270​
271### needsApproval?
272​
273```ts
274optional needsApproval: TNeedsApproval;
275```
276​
277Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:63](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L63)
278​
279If true, tool execution requires user approval before running. Works with both server and client tools.
280​
281#### Inherited from
282​
283[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`needsApproval`](ToolDefinitionInstance.md#needsapproval)
284​
285***
286​
287### outputSchema?
288​
289```ts
290optional outputSchema: TOutput;
291```
292​
293Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683)
294​
295Optional schema for validating tool output.
296​
297Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
298If provided with a Standard Schema compliant schema, tool results will be validated
299against this schema before being sent back to the model. This catches bugs in tool
300implementations and ensures consistent output formatting.
301​
302Note: This is client-side validation only - not sent to LLM providers.
303Note: Plain JSON Schema output validation is not performed at runtime.
304​
305#### Example
306​
307```ts
308// Using Zod
309z.object({
310 temperature: z.number(),
311 conditions: z.string(),
312 forecast: z.array(z.string()).optional()
313})
314```
315​
316#### Inherited from
317​
318[`ToolDefinitionInstance`](ToolDefinitionInstance.md).[`outputSchema`](ToolDefinitionInstance.md#outputschema)
319​
320***
321​
322### server()
323​
324```ts
325server: <TContext>(execute) => ServerTool<TInput, TOutput, TName, TContext>;
326```
327​
328Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:140](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L140)
329​
330Create a server-side tool with execute function
331​
332#### Type Parameters
333​
334##### TContext
335​
336`TContext` = `unknown`
337​
338#### Parameters
339​
340##### execute
341​
342[`ToolExecuteFunction`](../type-aliases/ToolExecuteFunction.md)\<`TInput`, `TOutput`, `TContext`\>
343​
344#### Returns
345​
346[`ServerTool`](ServerTool.md)\<`TInput`, `TOutput`, `TName`, `TContext`\>