agent/tools.ts

Source: sdks/typescript/packages/sdk/src/agent/tools.ts. Back to the TypeScript SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Type alias ToolKind

What a tool does, read by the continuation rules (exploration, verify_before_done).

Definition: "read" \| "write" \| "run" \| "verify".

Interface ToolDefinition

Definition of a local tool given to defineTool: name, description, input JSON Schema, handler and kind.

Fields:

Name	Type	Required	Description
name	string	yes	Name of the tool shown to the model.
description	string	yes	Description of the tool shown to the model.
inputSchema	Record<string	yes	JSON Schema of the input (draft 2020-12).
handler	(input: I, ctx: ToolContext) => Promise<O> | O	yes	Function that runs the tool with the validated input and the ToolContext.
kind	ToolKind	no	Default "run". A verify tool fails when it throws or returns { ok: false }.

Interface ToolContext

Context given to a tool handler: the step number and the optional AbortSignal.

Fields:

Name	Type	Required	Description
step	number	yes	Current step, free text (up to 500 characters).
signal	AbortSignal	no	AbortSignal of the run, to cancel long work.

Interface Tool

Tool returned by defineTool: its definition plus run (validates the input then runs the handler) and toOpenAI.

ToolDefinition<I, O>

This model declares no field.

Interface RemoteToolSpec

A tool run server side by the Tool Gateway (POST /v1/tools/{name}/invoke).

Fields:

Name	Type	Required	Description
name	string	yes	Name of the Tool Gateway tool, used in the invoke route and shown to the model.
description	string	no	Description of the tool shown to the model.
parameters	Record<string	no	Parameters of the operation.
kind	ToolKind	no	What a tool does, read by the continuation rules (exploration, verify_before_done).

Interface McpToolSpec

A tool of a registered MCP server, called through the MCP gateway (tools/call).

Fields:

Name	Type	Required	Description
name	string	yes	Name exposed to the model.
serverId	string	yes	Id of the registered MCP server that runs the tool.
tool	string	no	Tool name on the MCP server (default: name).
description	string	no	Description of the tool shown to the model.
parameters	Record<string	no	Parameters of the operation.
kind	ToolKind	no	What a tool does, read by the continuation rules (exploration, verify_before_done).

Functions

defineTool

defineTool(def: ToolDefinition<I, O>): Tool<I, O>

Declares a local tool with a JSON Schema validated input.

Name	Type	Default	Required	Description
def	ToolDefinition<I, O>		yes	Definition of the tool: name, description, input JSON Schema, handler and kind.

Returns: Tool<I, O>. The tool, whose run throws AgentLoopError tool_input_invalid when the input does not match the schema.

Raises: AgentLoopError.