API Reference

API reference for tool calling.

tool() Parameters

namerequiredstring

Unique identifier for the tool. The model uses the name to choose which tool to call.

descriptionrequiredstring

Functional description of the tool. Helps the model understand the tool's purpose and when to call it.

schemarequiredz.ZodObject

Zod Schema for parameters. Used both to describe the parameter structure to the model and to validate model-generated parameters.

executerequired(args: z.infer<T>) => ToolResult | Promise<ToolResult>

Tool execution function. Receives schema-validated parameters and returns an execution result of any type.

strictboolean

false

Enable strict mode for this tool. All tools in the same request must have the same strict value — mixing is not allowed. Alternatively, use createModel({ strict: true }) to enable strict mode globally. The SDK automatically switches to the Beta endpoint and passes strict: true to the API. The server validates the JSON Schema to ensure the model strictly follows the defined parameter structure.

requiredboolean

false

Mark as required tool. When enabled, the model is forced to call this tool.

timeoutnumber

60000

Execution timeout in milliseconds. Tool calls that exceed this time will be terminated.

retriesnumber

0

Maximum number of retries on failure. Each retry is subject to the timeout limit.

compactboolean | ToolCompactConfig

undefined

Enable result compaction. When true, tool results exceeding the threshold are compressed via an LLM to save context window space. Pass an object { threshold?: number, model?: Model } for custom settings.

Tool Type

ToolReturnType<typeof tool>

Return type of the tool() function. Contains the original configuration properties and processed parameters (JSON Schema) and execute (wrapped execution function).

StrictToolStrictTool

Tool with strict: true. All properties of this tool definition must have strict: true.

NonStrictToolNonStrictTool

Tool with strict: false or undefined. The default tool type when strict mode is not enabled.

ConsistentToolsStrictTool[] | NonStrictTool[]

Union type used by generateText and agent methods. Ensures all tools in an array have consistent strict mode settings — either all strict or all non-strict.