Defines the contract for tools that AI agents can invoke during conversation flows.

Tools extend agent capabilities with custom logic. Each tool requires a name, description (shown to the LLM), and a Zod input schema for validation. The execute function receives validated input and a ToolContext with conversation metadata.

Tools can require user approval before execution via requiresApproval. When set, the runtime emits an approval-required RuntimeEvent and waits for an ApprovalDecision. The flag supports both static booleans and dynamic functions for per-client configuration.

Related: AgentDefinition registers tools, AgentRuntime executes them, useAgentTool registers frontend-side tools.

interface ToolDefinition<TInput = unknown, TOutput = unknown> {
    name: string;
    description: string;
    inputSchema: unknown;
    outputSchema?: unknown;
    execute: (input: TInput, context: ToolContext) => Promise<TOutput>;
    requiresApproval?: boolean | ((context: ToolContext) => boolean);
    timeout?: number;
}