Tool

Defined in: src/tools/tool.ts:104

Interface for tool implementations. Tools are used by agents to interact with their environment and perform specific actions.

The Tool interface provides a streaming execution model where tools can yield progress events during execution before returning a final result.

Most implementations should use FunctionTool rather than implementing this interface directly.

Extended by

• InvokableTool
• FunctionTool
• ZodTool

Constructors

Constructor

new Tool(): Tool;

Returns

Tool

Properties

name

abstract name: string;

Defined in: src/tools/tool.ts:109

The unique name of the tool. This MUST match the name in the toolSpec.

---

description

abstract description: string;

Defined in: src/tools/tool.ts:116

Human-readable description of what the tool does. This helps the model understand when to use the tool.

This MUST match the description in the toolSpec.description.

---

toolSpec

abstract toolSpec: ToolSpec;

Defined in: src/tools/tool.ts:121

OpenAPI JSON specification for the tool. Defines the tool’s name, description, and input schema.

Methods

stream()

abstract stream(toolContext): ToolStreamGenerator;

Defined in: src/tools/tool.ts:156

Executes the tool with streaming support. Yields zero or more ToolStreamEvents during execution, then returns exactly one ToolResultBlock as the final value.

Parameters

| Parameter | Type | Description | | ------------- | -------------------------------- | ----------------------------------------------------------------------- | | toolContext | ToolContext | Context information including the tool use request and invocation state |

Returns

ToolStreamGenerator

Async generator that yields ToolStreamEvents and returns a ToolResultBlock

Example

const context = {
  toolUse: {
    name: 'calculator',
    toolUseId: 'calc-123',
    input: { operation: 'add', a: 5, b: 3 }
  },
}

// The return value is only accessible via explicit .next() calls
const generator = tool.stream(context)
for await (const event of generator) {
  // Only yields are captured here
  console.log('Progress:', event.data)
}
// Or manually handle the return value:
let result = await generator.next()
while (!result.done) {
  console.log('Progress:', result.value.data)
  result = await generator.next()
}
console.log('Final result:', result.value.status)