Skip to main content

Interface: ZodToolDefinition<TSchema, TReturn>

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

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​

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

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

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

description​

description: string

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

Description of what the tool does

execute​

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

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

The tool function to execute

Parameters​

params​

InferOutput<TSchema>

options?​

ToolExecutionOptions

Returns​

StreamingToolResult<TReturn>

function?​

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

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

Parameters​

params​

InferOutput<TSchema>

options?​

ToolExecutionOptions

Returns​

StreamingToolResult<TReturn>

Deprecated​

Use execute instead.

inputSchema​

inputSchema: TSchema

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

Zod schema for input validation

name​

name: string

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

Tool name (used in function calling)

needsApproval?​

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

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

Deprecated​

Use requiresApproval instead.

providerOptions?​

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

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

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

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. If not provided, the tool will be skipped.

Examples​

requiresApproval: true  // Always ask
requiresApproval: (params) => params.amount > 1000

strict?​

optional strict?: boolean

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

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

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​

toModelOutput: ({ output }) => ({
  type: 'text',
  value: `Found ${output.results.length} results. First: ${output.results[0]?.title}`
})
toModelOutput: ({ output }) => ({
  type: 'omit'  // Don't send API keys to model
})

toolGroup?​

optional toolGroup?: string

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

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