ToolDefinitionInstance

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:149

Tool definition that can be used directly or instantiated for server/client

Extends

• Tool<TInput, TOutput, TName, TContext>

Extended by

• ToolDefinition

Type Parameters

TInput

TInput extends SchemaInput | undefined = undefined

TOutput

TOutput extends SchemaInput | undefined = undefined

TName

TName extends string = string

TContext

TContext = unknown

TNeedsApproval

TNeedsApproval extends boolean = false

TApprovalSchema

TApprovalSchema extends | ApprovalSchemaConfig | undefined = undefined

Properties

__toolSide

__toolSide: "definition";

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:157

[toolApprovalCapability]?

readonly optional [toolApprovalCapability]?: object;

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:165

approvalSchema

approvalSchema: TApprovalSchema;

needsApproval

needsApproval: TNeedsApproval;

approvalSchema

approvalSchema: TApprovalSchema;

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:163

description

description: string;

Defined in: packages/ai/src/types.ts:980

Clear description of what the tool does.

This is crucial - the model uses this to decide when to call the tool. Be specific about what the tool does, what parameters it needs, and what it returns.

Example

"Get the current weather in a given location. Returns temperature, conditions, and forecast."

Inherited from

Tool.description

execute?

optional execute?: ToolExecuteFunction<TInput, TOutput, TContext>;

Defined in: packages/ai/src/types.ts:1060

Optional function to execute when the model calls this tool.

If provided, the SDK will automatically execute the function with the model's arguments and feed the result back to the model. This enables autonomous tool use loops.

Can return any value - will be automatically stringified if needed.

Param

args

The arguments parsed from the model's tool call (validated against inputSchema)

Returns

Result to send back to the model (validated against outputSchema if provided)

Example

execute: async (args) => {
  const weather = await fetchWeather(args.location);
  return weather; // Can return object or string
}

Inherited from

Tool.execute

execution?

optional execution?: "task";

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:164

inputSchema

inputSchema: TInput;

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:160

Schema describing the tool's input parameters.

Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object. Defines the structure and types of arguments the tool accepts. The model will generate arguments matching this schema. Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.

See

• https://standardschema.dev/json-schema
• https://json-schema.org/

Examples

// Using Zod v4+ schema (natively supports Standard JSON Schema)
import { z } from 'zod';
z.object({
  location: z.string().describe("City name or coordinates"),
  unit: z.enum(["celsius", "fahrenheit"]).optional()
})

// Using ArkType (natively supports Standard JSON Schema)
import { type } from 'arktype';
type({
  location: 'string',
  unit: "'celsius' | 'fahrenheit'"
})

// Using plain JSON Schema
{
  type: 'object',
  properties: {
    location: { type: 'string', description: 'City name or coordinates' },
    unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
  },
  required: ['location']
}

Overrides

Tool.inputSchema

lazy?

optional lazy?: boolean;

Defined in: packages/ai/src/types.ts:1066

If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).

Inherited from

Tool.lazy

metadata?

optional metadata?: Record<string, any>;

Defined in: packages/ai/src/types.ts:1077

Additional metadata for adapters or custom extensions

Inherited from

Tool.metadata

name

name: TName;

Defined in: packages/ai/src/types.ts:970

Unique name of the tool (used by the model to call it).

Should be descriptive and follow naming conventions (e.g., snake_case or camelCase). Must be unique within the tools array.

Example

"get_weather", "search_database", "sendEmail"

Inherited from

Tool.name

needsApproval?

optional needsApproval?: TNeedsApproval;

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:162

If true, tool execution requires user approval before running. Works with both server and client tools.

Overrides

Tool.needsApproval

outputSchema

outputSchema: TOutput;

Defined in: packages/ai/src/activities/chat/tools/tool-definition.ts:161

Optional schema for validating tool output.

Can be any Standard JSON Schema compliant schema or a plain JSON Schema object. If provided with a Standard Schema compliant schema, tool results will be validated against this schema before being sent back to the model. This catches bugs in tool implementations and ensures consistent output formatting.

Note: This is client-side validation only - not sent to LLM providers. Note: Plain JSON Schema output validation is not performed at runtime.

Example

// Using Zod
z.object({
  temperature: z.number(),
  conditions: z.string(),
  forecast: z.array(z.string()).optional()
})

Overrides

Tool.outputSchema

replay?

optional replay?: "safe" | "never";

Defined in: packages/ai/src/types.ts:1074

Whether a host may run this tool again after a crash cut the run between the call and its result. 'safe' runs it again. Omit the field, or set 'never', when a second run is not safe. The host writes the model note. chat() does not read this field.

Inherited from

Tool.replay