Open History to see the last commit
1---
2title: Tools
3id: tools
4order: 1
5description: "Define isomorphic AI tools in TanStack AI with toolDefinition() for type-safe server- and client-side function calling across any framework."
6keywords:
7 - tanstack ai
8 - tools
9 - function calling
10 - toolDefinition
11 - isomorphic tools
12 - server tools
13 - client tools
14 - type safety
15---
16
17Tools (also called "function calling") allow AI models to interact with external systems, APIs, or perform computations. TanStack AI provides an isomorphic tool system that enables type-safe, framework-agnostic tool definitions that work on both server and client.
18
19Tools enable your AI application to:
20
21- **Fetch data** from APIs or databases
22- **Perform calculations** or data transformations
23- **Interact with services** like email, calendars, or payment systems
24- **Execute client-side operations** like updating UI or local storage
25- **Create hybrid tools** that execute in both server and client contexts
26
27> Looking for provider-native tools like Anthropic web search, OpenAI code
28> interpreter, or Gemini URL context? See [Provider Tools](./provider-tools.md).
29
30## Framework Support
31
32TanStack AI works with **any** JavaScript framework:
33- TanStack Start, Next.js, Express, Remix, Fastify, etc.
34- React, Vue, Solid, Svelte, vanilla JS, etc.
35
36TanStack AI works with any JavaScript framework.
37
38## Isomorphic Tool Architecture
39
40TanStack AI uses a two-step tool definition process:
41
421. **Define once** with `toolDefinition()` - Creates a shared tool schema
432. **Implement** with `.server()` or `.client()` - Add execution logic for each environment
44
45This approach provides:
46
47- **Type Safety**: Full TypeScript inference from Zod schemas
48- **Code Reuse**: Define schemas once, use everywhere
49- **Flexibility**: Tools can execute on server, client, or both
50- **Schema Options**: Use Zod schemas or raw JSON Schema objects
51
52## Schema Options
53
54TanStack AI supports two ways to define tool schemas:
55
56### Option 1: Zod Schemas (Recommended)
57
58Zod schemas provide full TypeScript type inference and runtime validation:
59
60```typescript
61import { z } from "zod";
62
63const inputSchema = z.object({
64 location: z.string().meta({ description: "City name" }),
65 unit: z.enum(["celsius", "fahrenheit"]).optional(),
66});
67```
68
69### Option 2: JSON Schema Objects
70
71For cases where you already have JSON Schema definitions or prefer not to use Zod, you can pass raw JSON Schema objects directly:
72
73```typescript
74import type { JSONSchema } from "@tanstack/ai";
75
76const inputSchema: JSONSchema = {
77 type: "object",
78 properties: {
79 location: {
80 type: "string",
81 description: "City name",
82 },
83 unit: {
84 type: "string",
85 enum: ["celsius", "fahrenheit"],
86 },
87 },
88 required: ["location"],
89};
90```
91
92> **Note:** When using JSON Schema, TypeScript infers `unknown` for input/output types (it cannot derive types from a JSON Schema at compile time), so you must narrow or cast `args` before use. Zod schemas are recommended for full type safety.
93
94> **Tip:** Type safety from Zod schemas extends beyond tool execution — when you iterate over the stream returned by `chat()`, tool call events have typed `toolName` and `input` fields too. See [Type-Safe Tool Call Events](../chat/streaming#type-safe-tool-call-events).
95
96## Tool Definition
97
98Tools are defined using `toolDefinition()` from `@tanstack/ai`:
99
100```typescript
101import { toolDefinition } from "@tanstack/ai";
102import { z } from "zod";
103
104// Step 1: Define the tool schema
105const getWeatherDef = toolDefinition({
106 name: "get_weather",
107 description: "Get the current weather for a location",
108 inputSchema: z.object({
109 location: z.string().meta({ description: "The city and state, e.g. San Francisco, CA" }),
110 unit: z.enum(["celsius", "fahrenheit"]).optional(),
111 }),
112 outputSchema: z.object({
113 temperature: z.number(),
114 conditions: z.string(),
115 location: z.string(),
116 }),
117});
118
119// Step 2: Create a server implementation
120const getWeatherServer = getWeatherDef.server(async ({ location, unit }) => {
121 const response = await fetch(
122 `https://api.weather.com/v1/current?location=${location}&unit=${
123 unit || "fahrenheit"
124 }`
125 );
126 const data = await response.json();
127 return {
128 temperature: data.temperature,
129 conditions: data.conditions,
130 location: data.location,
131 };
132});
133```
134
135### Using JSON Schema
136
137If you prefer JSON Schema or have existing schema definitions:
138
139```typescript group=json-schema-tools
140import { toolDefinition } from "@tanstack/ai";
141import type { JSONSchema } from "@tanstack/ai";
142
143// Define schemas using JSON Schema
144const inputSchema: JSONSchema = {
145 type: "object",
146 properties: {
147 location: {
148 type: "string",
149 description: "The city and state, e.g. San Francisco, CA",
150 },
151 unit: {
152 type: "string",
153 enum: ["celsius", "fahrenheit"],
154 },
155 },
156 required: ["location"],
157};
158
159const outputSchema: JSONSchema = {
160 type: "object",
161 properties: {
162 temperature: { type: "number" },
163 conditions: { type: "string" },
164 location: { type: "string" },
165 },
166 required: ["temperature", "conditions", "location"],
167};
168
169// Create the tool definition
170const getWeatherDef = toolDefinition({
171 name: "get_weather",
172 description: "Get the current weather for a location",
173 inputSchema,
174 outputSchema,
175});
176
177// With a raw JSON Schema, `args` is `unknown` — narrow it before use
178// (prefer a Zod schema for automatic typing).
179const getWeatherServer = getWeatherDef.server(async (args) => {
180 if (typeof args !== "object" || args === null || !("location" in args)) {
181 throw new Error("Invalid input: expected a location");
182 }
183 const location = String(args.location);
184 const unit = "unit" in args ? String(args.unit) : "fahrenheit";
185 const response = await fetch(
186 `https://api.weather.com/v1/current?location=${location}&unit=${unit}`
187 );
188 return await response.json();
189});
190```
191
192## Using Tools in Chat
193
194### Server-Side
195
196```typescript
197import { chat, toServerSentEventsResponse, toolDefinition } from "@tanstack/ai";
198import { openaiText } from "@tanstack/ai-openai";
199import { z } from "zod";
200
201const getWeatherDef = toolDefinition({
202 name: "get_weather",
203 description: "Get the current weather for a location",
204 inputSchema: z.object({
205 location: z.string().meta({ description: "The city and state, e.g. San Francisco, CA" }),
206 unit: z.enum(["celsius", "fahrenheit"]).optional(),
207 }),
208 outputSchema: z.object({
209 temperature: z.number(),
210 conditions: z.string(),
211 location: z.string(),
212 }),
213});
214
215export async function POST(request: Request) {
216 const { messages } = await request.json();
217
218 // Create server implementation
219 const getWeather = getWeatherDef.server(async ({ location, unit }) => {
220 const response = await fetch(`https://api.weather.com/v1/current?...`);
221 return await response.json();
222 });
223
224 const stream = chat({
225 adapter: openaiText("gpt-5.5"),
226 messages,
227 tools: [getWeather], // Pass server tools
228 });
229
230 return toServerSentEventsResponse(stream);
231}
232```
233
234### Client-Side with Type Safety
235
236```tsx
237import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
238import {
239 createChatClientOptions,
240 type InferChatMessages
241} from "@tanstack/ai-client";
242import { toolDefinition } from "@tanstack/ai";
243import { z } from "zod";
244
245const updateUIDef = toolDefinition({
246 name: "updateUI",
247 description: "Update the UI with a notification message",
248 inputSchema: z.object({ message: z.string() }),
249 outputSchema: z.object({ success: z.boolean() }),
250});
251
252const saveToStorageDef = toolDefinition({
253 name: "saveToStorage",
254 description: "Save data to storage",
255 inputSchema: z.object({ key: z.string(), value: z.string() }),
256 outputSchema: z.object({ saved: z.boolean() }),
257});
258
259// Create client implementations
260const updateUI = updateUIDef.client((input) => {
261 // Update UI state
262 console.log(input.message);
263 return { success: true };
264});
265
266const saveToStorage = saveToStorageDef.client((input) => {
267 localStorage.setItem(input.key, input.value);
268 return { saved: true };
269});
270
271// Create typed tools array (no 'as const' needed!)
272const tools = [updateUI, saveToStorage];
273
274const textOptions = createChatClientOptions({
275 connection: fetchServerSentEvents("/api/chat"),
276 tools,
277});
278
279// Infer message types for full type safety
280type ChatMessages = InferChatMessages<typeof textOptions>;
281
282function ChatComponent() {
283 const { messages } = useChat(textOptions);
285 // messages is now fully typed with tool names and outputs!
286 return (
287 <div>
288 {messages.map((m) => (
289 <div key={m.id}>{m.role}</div>
290 ))}
291 </div>
292 );
293}
294```
295
296## Hybrid Tools
297
298Tools can be implemented for both server and client, enabling flexible execution patterns:
299
300```typescript group=tools
301import { toolDefinition, chat } from "@tanstack/ai";
302import { openaiText } from "@tanstack/ai-openai";
303import { z } from "zod";
304import { db } from "./db";
305
306// Define once
307const addToCartDef = toolDefinition({
308 name: "add_to_cart",
309 description: "Add item to shopping cart",
310 inputSchema: z.object({
311 itemId: z.string(),
312 quantity: z.number(),
313 }),
314 outputSchema: z.object({
315 success: z.boolean(),
316 cartId: z.string(),
317 }),
318 needsApproval: true,
319});
320
321// Server implementation - Store in database
322const addToCartServer = addToCartDef.server(async (input) => {
323 const cart = await db.carts.create({
324 data: { itemId: input.itemId, quantity: input.quantity },
325 });
326 return { success: true, cartId: cart.id };
327});
328
329// Client implementation - Update local wishlist
330const addToCartClient = addToCartDef.client((input) => {
331 const wishlist = JSON.parse(localStorage.getItem("wishlist") || "[]");
332 wishlist.push(input.itemId);
333 localStorage.setItem("wishlist", JSON.stringify(wishlist));
334 return { success: true, cartId: "local" };
335});
336```
337
338On the server, pass either the definition (for client execution) or the server implementation — in separate `chat()` calls:
339
340```typescript group=tools
341const messages = [{ role: 'user' as const, content: 'Add item abc to my cart' }]
342
343// Pass the definition: the client will execute the tool
344chat({
345 adapter: openaiText("gpt-5.5"),
346 messages,
347 tools: [addToCartDef],
348});
349
350// Or pass the server implementation: the server will execute the tool
351chat({
352 adapter: openaiText("gpt-5.5"),
353 messages,
354 tools: [addToCartServer],
355});
356```
357
358## Type Safety Benefits
359
360The isomorphic architecture provides complete type safety:
361
362```tsx
363import { useChat } from "@tanstack/ai-react";
364import { fetchServerSentEvents } from "@tanstack/ai-client";
365
366function CartChat() {
367 const { messages: uiMessages } = useChat({
368 connection: fetchServerSentEvents("/api/chat"),
369 });
370
371 // In your React component
372 uiMessages.forEach((message) => {
373 message.parts.forEach((part) => {
374 if (part.type === 'tool-call' && part.name === 'add_to_cart') {
375 // ✅ TypeScript knows part.name is literally 'add_to_cart'
376 // ✅ part.input is typed as { itemId: string, quantity: number }
377 // ✅ part.output is typed as { success: boolean, cartId: string } | undefined
379 if (part.output) {
380 console.log(part.output.cartId); // ✅ Fully typed!
381 }
382 }
383 });
384 });
385
386 return null;
387}
388```
389
390## Tool Execution Flow
391
3921. **Model decides to call a tool** - Based on user input and tool descriptions
3932. **Tool is identified** - Server or client implementation
3943. **Tool executes** - Automatically on server or client
3954. **Result is returned** - To the model as a tool result message
3965. **Model continues** - Uses the result to generate a response
397
398## Progress Events and Runtime Context
399
400A server tool's `.server()` implementation receives a second argument, the `ToolExecutionContext` — `{ context, toolCallId, emitCustomEvent }`. Use `emitCustomEvent` to stream typed progress to the client while the tool runs, and `context` to read request-scoped dependencies (auth, DB clients, etc.):
401
402```typescript
403import { toolDefinition } from "@tanstack/ai";
404import { z } from "zod";
405
406type ImportContext = {
407 db: {
408 read(source: string): Promise<unknown[]>;
409 write(rows: unknown[]): Promise<void>;
410 };
411};
412
413const importDataDef = toolDefinition({
414 name: "import_data",
415 description: "Import data from a source",
416 inputSchema: z.object({ source: z.string() }),
417 outputSchema: z.object({ imported: z.number() }),
418});
419
420const importData = importDataDef.server<ImportContext>(async (input, { context, emitCustomEvent }) => {
421 emitCustomEvent("progress", { step: 1, total: 3 });
422 const rows = await context.db.read(input.source);
423
424 emitCustomEvent("progress", { step: 2, total: 3 });
425 await context.db.write(rows);
426
427 emitCustomEvent("progress", { step: 3, total: 3 });
428 return { imported: rows.length };
429});
430```
431
432See [Server Tools](./server-tools) for the full runtime-context pattern.
433
434## Tool States
435
436Tools go through different states during execution:
437
438- `awaiting-input` - Tool call received, waiting for arguments
439- `input-streaming` - Partial arguments being streamed
440- `input-complete` - All arguments received
441- `approval-requested` - Tool requires user approval (if `needsApproval: true`)
442- `approval-responded` - User has approved/denied
443
444Once arguments (and approval, if required) are in, the result appears as `part.output` on the tool-call part and as a separate sibling `tool-result` part whose `state` is `complete` or `error`. See [Tool Architecture](./tool-architecture) for the full state model.
445
446> **Tip:** If your use case involves calling multiple tools with complex logic (filtering, aggregation, parallel calls), consider [Code Mode](../code-mode/code-mode) — it lets the LLM write a TypeScript program that orchestrates tools in a single execution instead of one tool call at a time.
447
448## Next Steps
449
450- [Server Tools](./server-tools) - Learn about server-side tool execution
451- [Client Tools](./client-tools) - Learn about client-side tool execution
452- [Tool Approval Flow](./tool-approval) - Implement approval workflows
453- [How Tools Work](./tool-architecture) - Deep dive into the tool architecture
454- [MCP Server Tools](./mcp) - Connect to external MCP servers for additional tools