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

ToolDefinitionInstance.md

281 lines6.5 KB

1---
2id: ToolDefinitionInstance
3title: ToolDefinitionInstance
4---
5​
6# Interface: ToolDefinitionInstance\<TInput, TOutput, TName\>
7​
8Defined in: [packages/typescript/ai/src/activities/chat/tools/tool-definition.ts:50](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L50)
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) = [`SchemaInput`](../type-aliases/SchemaInput.md)
25​
26### TOutput
27​
28`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
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: [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)
43​
44***
45​
46### description
47​
48```ts
49description: string;
50```
51​
52Defined in: [packages/typescript/ai/src/types.ts:509](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L509)
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, context?) => any;
75```
76​
77Defined in: [packages/typescript/ai/src/types.ts:589](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L589)
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##### context?
95​
96[`ToolExecutionContext`](ToolExecutionContext.md)
97​
98#### Returns
99​
100`any`
101​
102Result to send back to the model (validated against outputSchema if provided)
103​
104#### Example
105​
106```ts
107execute: async (args) => {
108 const weather = await fetchWeather(args.location);
109 return weather; // Can return object or string
111```
112​
113#### Inherited from
114​
115[`Tool`](Tool.md).[`execute`](Tool.md#execute)
116​
117***
118​
119### inputSchema?
120​
121```ts
122optional inputSchema: TInput;
123```
124​
125Defined in: [packages/typescript/ai/src/types.ts:549](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L549)
126​
127Schema describing the tool's input parameters.
128​
129Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
130Defines the structure and types of arguments the tool accepts.
131The model will generate arguments matching this schema.
132Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
133​
134#### See
135​
136 - https://standardschema.dev/json-schema
137 - https://json-schema.org/
138​
139#### Examples
140​
141```ts
142// Using Zod v4+ schema (natively supports Standard JSON Schema)
143import { z } from 'zod';
144z.object({
145 location: z.string().describe("City name or coordinates"),
146 unit: z.enum(["celsius", "fahrenheit"]).optional()
147})
148```
149​
150```ts
151// Using ArkType (natively supports Standard JSON Schema)
152import { type } from 'arktype';
153type({
154 location: 'string',
155 unit: "'celsius' | 'fahrenheit'"
156})
157```
158​
159```ts
160// Using plain JSON Schema
162 type: 'object',
163 properties: {
164 location: { type: 'string', description: 'City name or coordinates' },
165 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
166 },
167 required: ['location']
169```
170​
171#### Inherited from
172​
173[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
174​
175***
176​
177### lazy?
178​
179```ts
180optional lazy: boolean;
181```
182​
183Defined in: [packages/typescript/ai/src/types.ts:597](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L597)
184​
185If 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().
186​
187#### Inherited from
188​
189[`Tool`](Tool.md).[`lazy`](Tool.md#lazy)
190​
191***
192​
193### metadata?
194​
195```ts
196optional metadata: Record<string, any>;
197```
198​
199Defined in: [packages/typescript/ai/src/types.ts:600](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L600)
200​
201Additional metadata for adapters or custom extensions
202​
203#### Inherited from
204​
205[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
206​
207***
208​
209### name
210​
211```ts
212name: TName;
213```
214​
215Defined in: [packages/typescript/ai/src/types.ts:499](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L499)
216​
217Unique name of the tool (used by the model to call it).
218​
219Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
220Must be unique within the tools array.
221​
222#### Example
223​
224```ts
225"get_weather", "search_database", "sendEmail"
226```
227​
228#### Inherited from
229​
230[`Tool`](Tool.md).[`name`](Tool.md#name)
231​
232***
233​
234### needsApproval?
235​
236```ts
237optional needsApproval: boolean;
238```
239​
240Defined in: [packages/typescript/ai/src/types.ts:594](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L594)
241​
242If true, tool execution requires user approval before running. Works with both server and client tools.
243​
244#### Inherited from
245​
246[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
247​
248***
249​
250### outputSchema?
251​
252```ts
253optional outputSchema: TOutput;
254```
255​
256Defined in: [packages/typescript/ai/src/types.ts:570](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L570)
257​
258Optional schema for validating tool output.
259​
260Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
261If provided with a Standard Schema compliant schema, tool results will be validated
262against this schema before being sent back to the model. This catches bugs in tool
263implementations and ensures consistent output formatting.
264​
265Note: This is client-side validation only - not sent to LLM providers.
266Note: Plain JSON Schema output validation is not performed at runtime.
267​
268#### Example
269​
270```ts
271// Using Zod
272z.object({
273 temperature: z.number(),
274 conditions: z.string(),
275 forecast: z.array(z.string()).optional()
276})
277```
278​
279#### Inherited from
280​
281[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)