tool()

Tool is a helper function that infers the tool input and context for its execute method and lifecycle callbacks.

It does not have any runtime behavior, but it helps TypeScript infer the types for the tool callbacks.

Without this helper function, TypeScript is unable to connect the inputSchema and contextSchema properties to the tool callbacks, and the callback argument types cannot be inferred.

For the full model of runtimeContext, toolsContext, tool context, and sensitive context filtering, see Runtime and Tool Context.

The Tool type is a union of four tool kinds:

  • FunctionTool: a user-defined function-style tool with known input and output types.
  • DynamicTool: a function-style tool defined at runtime, with unknown input and output types.
  • ProviderDefinedTool: a provider-defined tool that your code executes.
  • ProviderExecutedTool: a provider-defined tool that the provider executes.
import { tool } from 'ai';
import { z } from 'zod';


export const weatherTool = tool({
  description: 'Get the weather in a location',
  inputSchema: z.object({
    location: z.string().describe('The location to get the weather for'),
  }),
  // location below is inferred to be a string:
  execute: async ({ location }) => ({
    location,
    temperature: 72 + Math.floor(Math.random() * 21) - 10,
  }),
});

Import 

import { tool } from "ai"

API Signature

Parameters

tool:

Tool
Tool

description?:

string | ((options: { context: CONTEXT; experimental_sandbox?: Experimental_SandboxSession }) => string)

title?:

string

needsApproval?:

boolean | ((input: INPUT, options: { toolCallId: string; messages: ModelMessage[]; context: CONTEXT }) => boolean | Promise<boolean>)

inputSchema:

Zod Schema | JSON Schema

inputExamples?:

Array<{ input: INPUT }>

contextSchema?:

Zod Schema | JSON Schema

strict?:

boolean

execute?:

async (input: INPUT, options: ToolExecutionOptions<CONTEXT>) => RESULT | Promise<RESULT> | AsyncIterable<RESULT>
ToolExecutionOptions<CONTEXT>

toolCallId:

string

messages:

ModelMessage[]

abortSignal?:

AbortSignal

context:

CONTEXT

experimental_sandbox?:

Experimental_SandboxSession

outputSchema?:

Zod Schema | JSON Schema

toModelOutput?:

({toolCallId: string; input: INPUT; output: OUTPUT}) => ToolResultOutput | PromiseLike<ToolResultOutput>

onInputStart?:

(options: ToolExecutionOptions<CONTEXT>) => void | PromiseLike<void>

onInputDelta?:

(options: { inputTextDelta: string } & ToolExecutionOptions<CONTEXT>) => void | PromiseLike<void>

onInputAvailable?:

(options: { input: INPUT } & ToolExecutionOptions<CONTEXT>) => void | PromiseLike<void>

providerOptions?:

ProviderOptions

metadata?:

JSONObject

type?:

'function' | 'dynamic' | 'provider'

id?:

`${string}.${string}`

isProviderExecuted?:

boolean

args?:

Record<string, unknown>

supportsDeferredResults?:

boolean

Returns

The tool that was passed in.