Open History to see the last commit
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
126}
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
177{
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']
184}
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)