Typed tool definitions
Create a model-callable action with validated, typed inputs.
AI Tools · Function
tool
tool() is a TypeScript helper for defining AI SDK tools with inferred input and context types. It connects schemas to execution and lifecycle callbacks without adding runtime behavior.
How it works
The AI SDK tool helper supplies TypeScript inference for a tool's input and execution callback. It has no runtime behavior; instead, it links inputSchema and contextSchema to the callback and lifecycle types.
Syntax
tool({ description, inputSchema, contextSchema, execute, ...callbacks })Parameters
| Name | Type | Description |
|---|---|---|
options | Tool options | Tool definition object containing the tool description, input schema, optional context schema, execute function, and lifecycle callbacks. |
Returns
A tool definition whose types are inferred from its schemas and callbacks; the helper itself has no runtime behavior.
Key points
- It infers both tool input and context types for
executeand lifecycle callbacks. - It connects
inputSchemaandcontextSchemawith callback types that TypeScript otherwise cannot associate. - A tool represents a model-invokable action for carrying out a defined task.
- The input schema serves both as model-facing tool information and as validation for generated calls.
- Providing
executeenables automatic execution when the model produces a matching tool call.
Common mistakes
- Do not expect
tool()to execute, validate, or otherwise alter runtime behavior; its role is compile-time type inference. - Without the helper, TypeScript cannot connect the schemas to callback arguments, so inference for those callbacks is lost.
Example: Typed tool definition
import { tool } from 'ai';
import { z } from 'zod';
const weatherTool = tool({
description: 'Get the weather in a location',
inputSchema: z.object({
location: z.string().describe('The location to get the weather for'),
}),
execute: async ({ location }) => ({ location, temperature: 22 }),
});The schema describes the input, while the helper connects that schema to the execute callback so TypeScript can infer its argument type.
When to use it
Callback type inference
Keep callback parameters synchronized with input and context schemas.
Model tool integration
Use tool definitions with text generation APIs that support tool calling.
Interview questions
QWhat problem does the tool() helper solve?
tool() is a helper for type inference. It links inputSchema and contextSchema to the tool's execute method and lifecycle callbacks, allowing TypeScript to infer callback argument types.
Follow-up: What happens at runtime? Nothing: the helper has no runtime behavior; execution belongs to the tool's callback and surrounding AI SDK flow.
QHow would you define a tool with typed inputs?
Define the tool with tool({ ... }), supplying the tool properties such as a description, an input schema, and an optional asynchronous execute function. The schema describes the input required for the tool to run.
Follow-up: How can the schema affect model behavior? Its description and structure are consumed by the model and used to validate generated tool calls.
QHow does a tool participate in a model call?
Tools are objects that a model can call for a specific task. If a tool has an execute function, the SDK runs it automatically when the model generates the corresponding call, and the result is returned as a tool result.
Follow-up: Why might execute be omitted? Calls may instead be forwarded to a client or queue for execution elsewhere.
Related
generateTextstreamTextinputSchemacontextSchemaexecutetool calltool result