Interface: ToolDefinition<TInput, TOutput, TName>

Defined in: tools/tool-definition.ts:95

Tool definition builder that allows creating server or client tools from a shared definition

Extends

ToolDefinitionInstance<TInput, TOutput, TName>

Type Parameters

TInput

TInput extends z.ZodType = z.ZodType

TOutput

TOutput extends z.ZodType = z.ZodType

TName

TName extends string = string

Properties

__toolSide

__toolSide: "definition";

__toolSide: "definition";

Defined in: tools/tool-definition.ts:43

Inherited from

ToolDefinitionInstance.__toolSide

client()

client: (execute?) => ClientTool<TInput, TOutput, TName>;

client: (execute?) => ClientTool<TInput, TOutput, TName>;

Defined in: tools/tool-definition.ts:112

Create a client-side tool with optional execute function

Parameters

execute?

(args) => output<TOutput> | Promise<output<TOutput>>

Returns

ClientTool<TInput, TOutput, TName>

description

description: string;

description: string;

Defined in: types.ts:279

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."

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

Inherited from

ToolDefinitionInstance.description

execute()?

optional execute: (args) => any;

optional execute: (args) => any;

Defined in: types.ts:335

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.

Parameters

args

any

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

Returns

any

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
}

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

Inherited from

ToolDefinitionInstance.execute

inputSchema?

optional inputSchema: TInput;

optional inputSchema: TInput;

Defined in: types.ts:298

Zod schema describing the tool's input parameters.

Defines the structure and types of arguments the tool accepts. The model will generate arguments matching this schema. The schema is converted to JSON Schema for LLM providers.

See

https://zod.dev/

Example

import { z } from 'zod';

z.object({
  location: z.string().describe("City name or coordinates"),
  unit: z.enum(["celsius", "fahrenheit"]).optional()
})

import { z } from 'zod';

z.object({
  location: z.string().describe("City name or coordinates"),
  unit: z.enum(["celsius", "fahrenheit"]).optional()
})

Inherited from

ToolDefinitionInstance.inputSchema

metadata?

optional metadata: Record<string, any>;

optional metadata: Record<string, any>;

Defined in: types.ts:341

Additional metadata for adapters or custom extensions

Inherited from

ToolDefinitionInstance.metadata

name

name: TName;

name: TName;

Defined in: types.ts:269

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"

"get_weather", "search_database", "sendEmail"

Inherited from

ToolDefinitionInstance.name

needsApproval?

optional needsApproval: boolean;

optional needsApproval: boolean;

Defined in: types.ts:338

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

Inherited from

ToolDefinitionInstance.needsApproval

outputSchema?

optional outputSchema: TOutput;

optional outputSchema: TOutput;

Defined in: types.ts:316

Optional Zod schema for validating tool output.

If provided, 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.

Example

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

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

Inherited from

ToolDefinitionInstance.outputSchema

server()

server: (execute) => ServerTool<TInput, TOutput, TName>;

server: (execute) => ServerTool<TInput, TOutput, TName>;

Defined in: tools/tool-definition.ts:103

Create a server-side tool with execute function