Skip to main content

Interface: ZodToolDefinition<TSchema, TReturn>

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

Zod-based tool definition (v2 - with inputSchema + v6 features)

Breaking change from v1:

  • v1: Used schema: TSchema
  • v2: Uses inputSchema: TSchema

v6 features added:

  • requiresApproval: Require user approval before execution
  • toModelOutput: Transform output before sending to model
  • strict: Enable strict JSON schema mode

Examples​

Basic tool

const weatherTool: ZodToolDefinition = {
  name: 'get_weather',
  description: 'Get weather info',
  inputSchema: z.object({
    location: z.string().describe('City name')
  }),
  execute: async (params) => {
    // params is { location: string }
    return { temp: 22, condition: 'sunny' };
  }
};

Tool with v6 features

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 };
  },
});

Type Parameters​

TSchema​

TSchema extends ZodType = ZodType

TReturn​

TReturn = unknown

Properties​

callers?​

optional callers?: string[]

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

Allowed callers for this tool (v6)

Specifies which execution contexts can invoke this tool. For Anthropic, maps to allowedCallers in provider options. Use 'code_execution' to allow Anthropic's PTC sandbox to call this tool.

Example​

callers: ['code_execution']  // Allow PTC sandbox to call this tool

deferLoading?​

optional deferLoading?: boolean

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

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:211

Description of what the tool does

execute​

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

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

The tool function to execute

Parameters​

params​

InferOutput<TSchema>

options?​

ToolExecutionOptions

Returns​

StreamingToolResult<TReturn>

inputSchema​

inputSchema: TSchema

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

Zod schema for input validation

name​

name: string

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

Tool name (used in function calling)

providerOptions?​

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

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

Provider-specific options for this tool (v6)

Passed through to the AI SDK's tool definition. Allows setting provider-specific behavior without the SDK needing to know details.

requiresApproval?​

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

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

Whether this tool requires user approval before execution (v6)

Can be:

  • true: Always require approval
  • false: Never require approval (default)
  • Function: Dynamically decide based on 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.

Examples​

Static approval

requiresApproval: true  // Always ask

Conditional approval

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

strict?​

optional strict?: boolean

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

Enable strict JSON schema mode (v6)

When true, the provider will enforce strict adherence to the schema. This can help prevent hallucinated parameters.

Default​

false

toModelOutput?​

optional toModelOutput?: (context) => ToolModelOutput

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

Transform tool output before sending to model (v6)

By default, tool output is JSON-stringified and sent to the model. Use this to customize what the model sees:

  • { type: 'text', value: '...' }: Send custom text
  • { type: 'content', value: [...] }: Send rich content blocks
  • { type: 'omit' }: Don't send output to model

Parameters​

context​
output​

TReturn

Returns​

ToolModelOutput

Examples​

Summarize large output

toModelOutput: ({ output }) => ({
  type: 'text',
  value: `Found ${output.results.length} results. First: ${output.results[0]?.title}`
})

Omit sensitive output

toModelOutput: ({ output }) => ({
  type: 'omit'  // Don't send API keys to model
})

toolGroup?​

optional toolGroup?: string

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

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