tools & tool calling

28 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Custom stream format example with tool calls

The StreamEvent type in this example is a union of three event types: {type: 'text'; text: string}, {type: 'tool-call'; toolName: string; input: unknown}, and {type: 'tool-result'; toolName: string; result: unknown}. This demonstrates how to define a custom streaming format that structures text deltas, tool invocations, and their results.

Streaming tool execution with yield for intermediate updates

Tool generate functions are async generators that can yield intermediate React components to show progress before returning a final result. Each yield sends an update to the client, allowing real-time feedback during long-running operations. The function returns a final component when complete. Example: async function* ({ repositoryName }) { yield <div>Cloning...</div>; await new Promise(resolve => setTimeout(resolve, 3000)); yield <div>Building...</div>; return <div>Done!</div>; }

Performance warning when using tool middleware on native function calling models

Using the custom tool call parser middleware on models that support native function calls may result in unintended performance degradation. Check whether your model supports native function calls before deciding to use this middleware.

addToolInputExamplesMiddleware function and options

The addToolInputExamplesMiddleware function adds tool input examples to tool descriptions for providers that don't natively support the inputExamples property. It accepts the following options: prefix (optional, default 'Input Examples:') - text prepended before examples; format (optional) - custom formatter function receiving example object and index, default is JSON.stringify(example.input); remove (optional, default true) - whether to remove the inputExamples property from the tool after adding to description.

Community middleware: Custom tool call parser

The @ai-sdk-tool/parser package provides middleware variants for adding function calling to models that don't natively support it: createToolMiddleware (flexible function for custom tool call middleware), hermesToolMiddleware (ready-to-use for Hermes & Qwen format), and gemmaToolMiddleware (pre-configured for Gemma 3 models).

ToolExecutionOptions interface

ToolExecutionOptions passed to a tool's execute function contains: - toolCallId (string): The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data. - messages (ModelMessage[]): Messages that were sent to the language model to initiate the response that contained the tool call. The messages do not include the system prompt nor the assistant response that contained the tool call. - abortSignal (AbortSignal): An optional abort signal that indicates that the overall operation should be aborted.

Tool definition structure in generateText

Tools in generateText are defined with the following properties: - description (string | ((options: { context: CONTEXT; experimental_sandbox?: Experimental_SandboxSession }) => string), optional): Information about the purpose of the tool including details on how and when it can be used by the model. Provide a string for a fixed description, or a function to derive the description from the tool-specific context and optional experimental sandbox before each model call. - inputSchema (Zod Schema | JSON Schema): The schema of the input that the tool expects. The language model will use this to generate the input. It is also used to validate the output of the language model. Use descriptions to make the input understandable for the language model. You can either pass in a Zod schema or a JSON schema (using the jsonSchema function). - execute (async (parameters: T, options: ToolExecutionOptions) => RESULT, optional): An async function that is called with the arguments from the tool call and produces a result. If not provided, the tool will not be executed automatically.

tool helper function description

tool() is a type inference helper function for tools.

Experimental_SandboxSession interface description

Experimental_SandboxSession is an experimental execution environment interface passed to tool execution.

experimental_filterActiveTools function description

experimental_filterActiveTools() filters a tool set to only the currently active tools.

experimental_getRealtimeToolDefinitions function description

experimental_getRealtimeToolDefinitions() converts AI SDK tools into realtime tool definitions.

MCP Apps helper description

MCP Apps provides helpers for rendering interactive MCP tool UIs and filtering app-visible tools.

ToolCallRepairOptions structure

ToolCallRepairOptions contains: instructions (Instructions | undefined), system (Instructions | undefined, deprecated - use instructions instead), messages (ModelMessage[] - messages in the current generation step), toolCall (LanguageModelV4ToolCall - the tool call that failed to parse), tools (TOOLS - available tools), inputSchema (function that returns JSONSchema7 for a tool given toolName), and error (NoSuchToolError | InvalidToolInputError - the error that occurred while parsing).

streamText onToolExecutionStart callback

The onToolExecutionStart callback is called right before a tool's execute function runs. It receives ToolExecutionStartEvent with: callId (string, unique identifier to correlate events), toolCall (TypedToolCall<TOOLS>), messages (Array<ModelMessage> sent to model, excluding system prompt and assistant response), and toolContext (tool-specific context narrowed to individual tool type). Errors are silently caught.

streamText onToolExecutionEnd callback

The onToolExecutionEnd callback is called after a tool's execute function completes or errors. It receives ToolExecutionEndEvent with: callId (string), toolCall (TypedToolCall<TOOLS>), toolExecutionMs (number, wall-clock duration), messages (Array<ModelMessage> sent to model), toolContext (tool-specific context narrowed to individual tool), and toolOutput (discriminated union where type='tool-result' has output field, type='tool-error' has error field). Errors are silently caught.

streamText experimental_onToolCallFinish deprecated callback

The experimental_onToolCallFinish callback is deprecated. Use onToolExecutionEnd instead. It is only used as a fallback when onToolExecutionEnd is not provided.

ActiveTools type definition and behavior

ActiveTools is a generic type defined as type ActiveTools<TOOLS extends ToolSet> = ReadonlyArray<keyof TOOLS & string> | undefined. It limits a generation step to the listed tool names. When undefined, no tool restriction is applied.

ToolModelMessage structure

ToolModelMessage has role: 'tool' and content: Array<ToolResultPart>. Each ToolResultPart contains type: 'tool-result', toolCallId: string, toolName: string, result: unknown, and optional isError: boolean indicating whether the result is an error.

streamText parameter: tools

The 'tools' parameter is of type ToolSet and is optional. It defines tools that are accessible to and can be called by the model. The model needs to support calling tools.

Tool object structure

A Tool object contains: description (optional, type: string or function that derives description from context), inputSchema (required, type: Zod Schema or JSON Schema), and execute (optional, type: async function). The description provides information about the tool's purpose and usage. The inputSchema defines what inputs the tool expects. The execute function is called with the tool arguments and options containing toolCallId, messages, and abortSignal.

streamText parameter: toolChoice

The 'toolChoice' parameter is of type '"auto" | "none" | "required" | { "type": "tool", "toolName": string }' and is optional, defaulting to 'auto'. It specifies how tools are selected for execution: 'auto' allows automatic selection, 'none' disables tool execution, 'required' requires tools to be executed, and the object form specifies a specific tool to execute.

streamText parameter: activeTools

The 'activeTools' parameter is of type ActiveTools<TOOLS> and is optional. It limits the tools that are available for the model to call without changing the tool call and result types in the result. All tools are active by default. Tool names are restricted to the string keys of the tool set.

streamText parameter: toolOrder

The 'toolOrder' parameter is of type ToolOrder<TOOLS> and is optional. It controls the order in which tools are sent to the provider. The list can be partial. Tools not listed in toolOrder are sent after the listed tools, sorted alphabetically. Tool names are restricted to the string keys of the tool set.

streamText parameter: toolApproval

The 'toolApproval' parameter is of type ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT> and is optional. It configures approval for tool calls. Pass a GenericToolApprovalFunction to handle all tool calls in one callback, or pass a per-tool object where each key can be a status ('not-applicable', 'approved', 'denied', or 'user-approval'), an object form like { type: 'denied', reason: 'blocked by policy' }, or a SingleToolApprovalFunction. 'not-applicable' is the default and runs the tool without approval metadata. Use 'approved' or 'denied' for explicit automatic approvals with optional reason fields.

streamText parameter: experimental_toolCallers

The 'experimental_toolCallers' parameter is of type Experimental_ToolCallers<TOOLS> and is optional. It configures which caller tools may invoke each tool, passed as an object keyed by callee tool name with values listing caller-capable tool names. Include DIRECT_TOOL_CALL from @ai-sdk/code-mode to keep a tool directly callable. Local-only callees are hidden from direct model calls and bound to their local caller for each generation step.

streamText parameter: experimental_refineToolInput

The 'experimental_refineToolInput' parameter is of type ToolInputRefinement<TOOLS> and is optional. It is an optional mapping of tool names to functions that refine parsed tool inputs. Each function receives the typed input for its tool and must return the same input type shape. The refined input is used for tool execution, stream parts, lifecycle callbacks, and telemetry.

streamText parameter: toolsContext

The 'toolsContext' parameter is of type InferToolSetContext<TOOLS>. It is a per-tool context map keyed by tool name. It is required when at least one tool defines contextSchema; not accepted when no tools need context.

streamText parameter: repairToolCall

The 'repairToolCall' parameter is of type function (options: ToolCallRepairOptions) => Promise<LanguageModelV4ToolCall | null> and is optional. It is a function that attempts to repair a tool call that failed to parse. Return either a repaired tool call or null if the tool call cannot be repaired.

Give your agent this brain