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
ToolDurability<InferOutput<TSchema>,TReturn>.ToolPresentation<InferOutput<TSchema>>
Type Parameters
TSchema
TSchema extends ZodType = ZodType
TReturn
TReturn = unknown
Properties
callers?
optionalcallers?: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?
optionalcapability?:ToolCapability
Defined in: packages/core/src/utils/tools.ts:220
Undeclared: 'both', so a read-only mode leaves the tool out.
Inherited from
childRun?
optionalchildRun?: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
deferLoading?
optionaldeferLoading?: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?
optionaldisplay?:ToolDisplay<InferOutput<TSchema>>
Defined in: packages/core/src/utils/tools.ts:218
Inherited from
execute
execute: (
params,options?) =>StreamingToolResult<TReturn>
Defined in: packages/core/src/utils/tools.ts:453
Parameters
params
InferOutput<TSchema>
options?
Returns
StreamingToolResult<TReturn>
inputExamples?
optionalinputExamples?: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?
optionaloutputLimit?: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?
optionalproviderOptions?:Record<string,Record<string,unknown>>
Defined in: packages/core/src/utils/tools.ts:415
Passed through to the AI SDK tool definition unchanged.
reconcile?
optionalreconcile?: (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
Returns
Promise<EffectReconciliation<TReturn>>
Inherited from
replay?
optionalreplay?: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
requiresApproval?
optionalrequiresApproval?: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?
optionalstrict?: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?
optionaltimeoutMs?: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
toModelOutput?
optionaltoModelOutput?: (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
toolGroup?
optionaltoolGroup?: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?
optionalversion?:string
Defined in: packages/core/src/utils/tools.ts:104
Semantic version. Required only for strict durability.
Inherited from
Methods
describeApproval()?
optionaldescribeApproval(input):ToolApprovalSummary|undefined
Defined in: packages/core/src/utils/tools.ts:222
Describes a call that needs approval (see requiresApproval).
Parameters
input
Returns
ToolApprovalSummary | undefined