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

ProviderTool.md

297 lines6.9 KB

1---
2id: ProviderTool
3title: ProviderTool
4---
5​
6# Interface: ProviderTool\<TProvider, TKind\>
7​
8Defined in: [packages/typescript/ai/src/tools/provider-tool.ts:19](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/provider-tool.ts#L19)
9​
10A provider-specific tool produced by an adapter-package factory
11(e.g. `webSearchTool` from `@tanstack/ai-anthropic/tools`).
12​
13The two `~`-prefixed fields are type-only phantom brands — they are never
14assigned at runtime. They allow the core type system to match a factory's
15output against the selected model's `supports.tools` list and surface a
16compile-time error when the combination is unsupported.
17​
18User-defined tools (via `toolDefinition()`) remain plain `Tool` and stay
19assignable to any model.
20​
21## Extends
22​
23- [`Tool`](Tool.md)
24​
25## Type Parameters
26​
27### TProvider
28​
29`TProvider` *extends* `string`
30​
31Provider identifier (e.g. `'anthropic'`, `'openai'`).
32​
33### TKind
34​
35`TKind` *extends* `string`
36​
37Canonical tool-kind string matching the provider's
38 `supports.tools` entries (e.g. `'web_search'`, `'code_execution'`).
39​
40## Properties
41​
42### ~provider
43​
44```ts
45readonly ~provider: TProvider;
46```
47​
48Defined in: [packages/typescript/ai/src/tools/provider-tool.ts:23](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/provider-tool.ts#L23)
49​
50***
51​
52### ~toolKind
53​
54```ts
55readonly ~toolKind: TKind;
56```
57​
58Defined in: [packages/typescript/ai/src/tools/provider-tool.ts:24](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/provider-tool.ts#L24)
59​
60***
61​
62### description
63​
64```ts
65description: string;
66```
67​
68Defined in: [packages/typescript/ai/src/types.ts:509](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L509)
69​
70Clear description of what the tool does.
71​
72This is crucial - the model uses this to decide when to call the tool.
73Be specific about what the tool does, what parameters it needs, and what it returns.
74​
75#### Example
76​
77```ts
78"Get the current weather in a given location. Returns temperature, conditions, and forecast."
79```
80​
81#### Inherited from
82​
83[`Tool`](Tool.md).[`description`](Tool.md#description)
84​
85***
86​
87### execute()?
88​
89```ts
90optional execute: (args, context?) => any;
91```
92​
93Defined in: [packages/typescript/ai/src/types.ts:589](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L589)
94​
95Optional function to execute when the model calls this tool.
96​
97If provided, the SDK will automatically execute the function with the model's arguments
98and feed the result back to the model. This enables autonomous tool use loops.
99​
100Can return any value - will be automatically stringified if needed.
101​
102#### Parameters
103​
104##### args
105​
106`any`
107​
108The arguments parsed from the model's tool call (validated against inputSchema)
109​
110##### context?
111​
112[`ToolExecutionContext`](ToolExecutionContext.md)
113​
114#### Returns
115​
116`any`
117​
118Result to send back to the model (validated against outputSchema if provided)
119​
120#### Example
121​
122```ts
123execute: async (args) => {
124 const weather = await fetchWeather(args.location);
125 return weather; // Can return object or string
127```
128​
129#### Inherited from
130​
131[`Tool`](Tool.md).[`execute`](Tool.md#execute)
132​
133***
134​
135### inputSchema?
136​
137```ts
138optional inputSchema: SchemaInput;
139```
140​
141Defined in: [packages/typescript/ai/src/types.ts:549](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L549)
142​
143Schema describing the tool's input parameters.
144​
145Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
146Defines the structure and types of arguments the tool accepts.
147The model will generate arguments matching this schema.
148Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
149​
150#### See
151​
152 - https://standardschema.dev/json-schema
153 - https://json-schema.org/
154​
155#### Examples
156​
157```ts
158// Using Zod v4+ schema (natively supports Standard JSON Schema)
159import { z } from 'zod';
160z.object({
161 location: z.string().describe("City name or coordinates"),
162 unit: z.enum(["celsius", "fahrenheit"]).optional()
163})
164```
165​
166```ts
167// Using ArkType (natively supports Standard JSON Schema)
168import { type } from 'arktype';
169type({
170 location: 'string',
171 unit: "'celsius' | 'fahrenheit'"
172})
173```
174​
175```ts
176// Using plain JSON Schema
178 type: 'object',
179 properties: {
180 location: { type: 'string', description: 'City name or coordinates' },
181 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
182 },
183 required: ['location']
185```
186​
187#### Inherited from
188​
189[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
190​
191***
192​
193### lazy?
194​
195```ts
196optional lazy: boolean;
197```
198​
199Defined in: [packages/typescript/ai/src/types.ts:597](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L597)
200​
201If 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().
202​
203#### Inherited from
204​
205[`Tool`](Tool.md).[`lazy`](Tool.md#lazy)
206​
207***
208​
209### metadata?
210​
211```ts
212optional metadata: Record<string, any>;
213```
214​
215Defined in: [packages/typescript/ai/src/types.ts:600](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L600)
216​
217Additional metadata for adapters or custom extensions
218​
219#### Inherited from
220​
221[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
222​
223***
224​
225### name
226​
227```ts
228name: string;
229```
230​
231Defined in: [packages/typescript/ai/src/types.ts:499](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L499)
232​
233Unique name of the tool (used by the model to call it).
234​
235Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
236Must be unique within the tools array.
237​
238#### Example
239​
240```ts
241"get_weather", "search_database", "sendEmail"
242```
243​
244#### Inherited from
245​
246[`Tool`](Tool.md).[`name`](Tool.md#name)
247​
248***
249​
250### needsApproval?
251​
252```ts
253optional needsApproval: boolean;
254```
255​
256Defined in: [packages/typescript/ai/src/types.ts:594](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L594)
257​
258If true, tool execution requires user approval before running. Works with both server and client tools.
259​
260#### Inherited from
261​
262[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
263​
264***
265​
266### outputSchema?
267​
268```ts
269optional outputSchema: SchemaInput;
270```
271​
272Defined in: [packages/typescript/ai/src/types.ts:570](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L570)
273​
274Optional schema for validating tool output.
275​
276Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
277If provided with a Standard Schema compliant schema, tool results will be validated
278against this schema before being sent back to the model. This catches bugs in tool
279implementations and ensures consistent output formatting.
280​
281Note: This is client-side validation only - not sent to LLM providers.
282Note: Plain JSON Schema output validation is not performed at runtime.
283​
284#### Example
285​
286```ts
287// Using Zod
288z.object({
289 temperature: z.number(),
290 conditions: z.string(),
291 forecast: z.array(z.string()).optional()
292})
293```
294​
295#### Inherited from
296​
297[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)