Skip to content

Tools API Reference

Overview of the tools API and built-in tools.

Interfaces

Tool

interface Tool<P extends z.ZodType, M = unknown> {
  name: string;
  description: string;
  parameters: P;
  executor: (params: z.infer<P>) => Promise<ToolResult<M>> | ToolResult<M>;
}

ToolProvider

interface ToolProvider {
  name: string;
  initialize?(): Promise<void>;
  getTools(): BaseTool[];
  dispose?(): Promise<void>;
}

ToolResult

interface ToolResult<M = unknown> {
  content: string | ContentBlock[];
  metadata?: M;
}

Built-in Tools

SIMPLE_FINISH_TOOL

Signal task completion:

import { SIMPLE_FINISH_TOOL, type FinishParams } from '@stirrup/stirrup';

// Schema
interface FinishParams {
  reason: string;      // Summary of what was done
  paths: string[];     // Output file paths
}

// Usage
const agent = new Agent({
  client,
  finishTool: SIMPLE_FINISH_TOOL,
});

CALCULATOR_TOOL

Perform calculations:

import { CALCULATOR_TOOL } from '@stirrup/stirrup';

// Schema
interface CalculatorParams {
  expression: string;  // Math expression to evaluate
}

// Usage
const agent = new Agent({
  client,
  tools: [CALCULATOR_TOOL],
});

DEFAULT_TOOLS

Standard tool set (code execution + web):

import { DEFAULT_TOOLS } from '@stirrup/stirrup';

// Includes:
// - LocalCodeExecToolProvider
// - WebToolProvider

const agent = new Agent({
  client,
  tools: DEFAULT_TOOLS,
});

Metadata Classes

ToolUseCountMetadata

class ToolUseCountMetadata {
  numUses: number;

  constructor(count: number = 1);
  merge(other: ToolUseCountMetadata): ToolUseCountMetadata;
}

WebFetchMetadata

class WebFetchMetadata {
  numFetches: number;
  totalBytes: number;

  merge(other: WebFetchMetadata): WebFetchMetadata;
}

WebSearchMetadata

class WebSearchMetadata {
  numSearches: number;
  numResults: number;

  merge(other: WebSearchMetadata): WebSearchMetadata;
}

See Also