Skip to main content

Interface: ZodToolDefinition<TSchema, TReturn>

Defined in: packages/core/src/utils/tools.ts:365

A tool whose input is described by a Zod schema, so execute's parameters are inferred from it.

Examples​

Approval, strict schema and model output

const dangerousTool = defineZodTool({
name: 'delete_file',
description: 'Delete a file from the system',
inputSchema: z.object({ path: z.string() }),
requiresApproval: true, // Always require approval
strict: true, // Use strict JSON schema mode
toModelOutput: ({ output }) => ({
type: 'text',
value: output.success ? 'File deleted' : 'Delete failed'
}),
execute: async ({ path }) => {
await fs.unlink(path);
return { success: true };
},
});

Conditional approval

const fileTool = defineZodTool({
name: 'write_file',
description: 'Write content to a file',
inputSchema: z.object({
path: z.string(),
content: z.string()
}),
// Only require approval for sensitive paths
requiresApproval: (params) => {
return params.path.startsWith('/etc/') ||
params.path.includes('.env');
},
execute: async ({ path, content }) => {
await fs.writeFile(path, content);
return { written: true };
},
});

Extends​

Type Parameters​

TSchema​

TSchema extends ZodType = ZodType

TReturn​

TReturn = unknown

Properties​

callers?​

optional callers?: string[]

Defined in: packages/core/src/utils/tools.ts:412

Which execution contexts may call this tool. For Anthropic it becomes allowedCallers in provider options; 'code_execution' lets Anthropic's programmatic tool calling sandbox call it.

Example​

callers: ['code_execution']

capability?​

optional capability?: ToolCapability

Defined in: packages/core/src/utils/tools.ts:220

Undeclared: 'both', so a read-only mode leaves the tool out.

Inherited from​

ToolPresentation.capability


childRun?​

optional childRun?: boolean

Defined in: packages/core/src/utils/tools.ts:119

The tool runs a child loop (a subagent) inside its call. Its own loop has its own limits, so the call gets no tool limit unless it declares timeoutMs, and the parent's loop needs the place's childRecovery. A Processable tool runs one without declaring it. See declareChildRun().

Inherited from​

ToolDurability.childRun


deferLoading?​

optional deferLoading?: boolean

Defined in: packages/core/src/utils/tools.ts:426

Mark this tool as deferred — it won't be included in the initial prompt. Use splitTools() to partition tools by this flag.

The AI SDK adapter maps this flag to Anthropic's providerOptions.anthropic.deferLoading option. Native deferred discovery also requires an Anthropic provider-defined tool search tool, such as anthropic.tools.toolSearchBm25_20251119().


description​

description: string

Defined in: packages/core/src/utils/tools.ts:370


display?​

optional display?: ToolDisplay<InferOutput<TSchema>>

Defined in: packages/core/src/utils/tools.ts:218

Inherited from​

ToolPresentation.display


execute​

execute: (params, options?) => StreamingToolResult<TReturn>

Defined in: packages/core/src/utils/tools.ts:453

Parameters​

params​

InferOutput<TSchema>

options?​

ToolExecutionOptions

Returns​

StreamingToolResult<TReturn>


inputExamples?​

optional inputExamples?: object[]

Defined in: packages/core/src/utils/tools.ts:436

Example inputs that show the model how to call this tool — most useful for free-form or nested payloads (Anthropic measured complex-parameter accuracy rising from 72% to 90% with them). Sent natively as Anthropic input_examples; on other providers they are folded into the description (AI SDK addToolInputExamplesMiddleware). Each example must satisfy the input schema.

input​

input: InferOutput<TSchema>


inputSchema​

inputSchema: TSchema

Defined in: packages/core/src/utils/tools.ts:371


name​

name: string

Defined in: packages/core/src/utils/tools.ts:369


outputLimit?​

optional outputLimit?: number | false

Defined in: packages/core/src/utils/tools.ts:445

Cap on the result's size, in characters, before the model sees it. Default 10,000 (a longer result is cut, as text or as JSON; see capToolOutput). false sends the whole result — for a tool whose full output is the point, such as a sub-agent's report. Only the model's view is cut: stop conditions, the step's tool results and events read the result the tool returned.


providerOptions?​

optional providerOptions?: Record<string, Record<string, unknown>>

Defined in: packages/core/src/utils/tools.ts:415

Passed through to the AI SDK tool definition unchanged.


reconcile?​

optional reconcile?: (toolCallId, input) => Promise<EffectReconciliation<TReturn>>

Defined in: packages/core/src/utils/tools.ts:102

What an interrupted call did, looked up by its toolCallId.

Parameters​

toolCallId​

string

input​

InferOutput

Returns​

Promise<EffectReconciliation<TReturn>>

Inherited from​

ToolDurability.reconcile


replay?​

optional replay?: ToolReplay

Defined in: packages/core/src/utils/tools.ts:100

'safe': may run again with the same toolCallId. 'unsafe': never runs again without reconciling.

Inherited from​

ToolDurability.replay


requiresApproval?​

optional requiresApproval?: boolean | ((params) => boolean | Promise<boolean>)

Defined in: packages/core/src/utils/tools.ts:386

Whether a call needs the user's approval before it runs: true, false (default), or decided per call from its parameters.

When approval is required, onApprovalRequired in ProcessOptions will be called (in-process await). If not provided, the loop pauses with a tool_approval_request and resumes via approvalResponses.

Example​

requiresApproval: (params) => params.amount > 1000

strict?​

optional strict?: boolean

Defined in: packages/core/src/utils/tools.ts:394

Ask the provider to hold the model's input to the schema exactly (provider strict mode).

Default​

false

timeoutMs?​

optional timeoutMs?: number | false

Defined in: packages/core/src/utils/tools.ts:112

This tool's limit per call in a checkpointed durable loop, in milliseconds from the call's start (AI SDK timeout.tools): past it the call's abortSignal aborts and the call ends as a tool error. false: no limit. Unset: the run's RunPolicy.toolTimeoutMs, else its stepIdleTimeoutMs. Wins over childRun, so a host can bound a child loop too.

Inherited from​

ToolDurability.timeoutMs


toModelOutput?​

optional toModelOutput?: (context) => ToolModelOutput

Defined in: packages/core/src/utils/tools.ts:400

What the model sees of the result (see ToolModelOutput). Without it the result is JSON-stringified.

Parameters​

context​
output​

TReturn

Returns​

ToolModelOutput


toolGroup?​

optional toolGroup?: string

Defined in: packages/core/src/utils/tools.ts:451

Logical group for filtering (e.g., 'search', 'filesystem', 'database'). Use filterToolsByGroup() to select tools by group.


version?​

optional version?: string

Defined in: packages/core/src/utils/tools.ts:104

Semantic version. Required only for strict durability.

Inherited from​

ToolDurability.version

Methods​

describeApproval()?​

optional describeApproval(input): ToolApprovalSummary | undefined

Defined in: packages/core/src/utils/tools.ts:222

Describes a call that needs approval (see requiresApproval).

Parameters​

input​

InferOutput

Returns​

ToolApprovalSummary | undefined

Inherited from​

ToolPresentation.describeApproval