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

ToolDefinitionInstance.md

279 lines6.5 KB

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