Tools

This interface is experimental — no production implementation exists yet. The API surface may change.

Overview

Tools provides a unified surface for agent tool discovery and execution. Agents call tools without needing to know whether they originate from MCP servers, built-in capabilities, or custom providers — the implementation aggregates all sources transparently. Provider analogues include Anthropic MCP Tools, OpenAI Function Calling, Vercel AI SDK Tools, and LangChain Tools.

TypeScript API

import type { Tool, ToolResult, Tools } from "osprotocol/actions/tools"

Tool

Represents a single callable tool with a name, description, parameter schema, and execute function.

interface Tool<TParams = unknown, TResult = unknown> {
  name: string
  description: string
  parameters?: object
  execute(params: TParams): Promise<TResult>
  metadata?: Record<string, unknown>
}

Field	Type	Description
`name`	`string`	Unique tool identifier
`description`	`string`	Human-readable description of what the tool does
`parameters`	`object`	Optional JSON Schema describing accepted parameters
`execute`	`(params: TParams) => Promise<TResult>`	Function that performs the tool action
`metadata`	`Record<string, unknown>`	Optional extra data attached to the tool

ToolResult

Returned by Tools.execute. Wraps the result with success/error state.

interface ToolResult<T = unknown> {
  toolName: string
  result: T
  success: boolean
  error?: string
  metadata?: Record<string, unknown>
}

Field	Type	Description
`toolName`	`string`	Name of the tool that was executed
`result`	`T`	The value returned by the tool
`success`	`boolean`	Whether execution completed without error
`error`	`string`	Error message if `success` is `false`
`metadata`	`Record<string, unknown>`	Optional extra data from the execution

The primary interface agents use to discover and invoke tools.

interface Tools {
  get(name: string): Promise<Tool | null>
  list(): Promise<Tool[]>
  execute<T = unknown>(name: string, params?: unknown): Promise<ToolResult<T>>
}

Method	Returns	Description
`get(name)`	`Promise<Tool \| null>`	Retrieve a tool by name, or `null` if not found
`list()`	`Promise<Tool[]>`	Return all available tools from all registered sources
`execute(name, params?)`	`Promise<ToolResult<T>>`	Invoke a tool by name with optional parameters

Usage Examples

Execute a tool

const result = await tools.execute("read_file", { path: "/data/config.json" })

if (result.success) {
  console.log(result.result)
} else {
  console.error(result.error)
}

List available tools and find one

const allTools = await tools.list()
const searchTool = allTools.find((t) => t.name === "web_search")

if (searchTool) {
  console.log(searchTool.description)
  console.log(searchTool.parameters)
}

Handle tool errors

const result = await tools.execute<string>("send_email", {
  to: "user@example.com",
  subject: "Hello",
  body: "Message body",
})

if (!result.success) {
  // Log the error and fall back gracefully
  console.error(`Tool "${result.toolName}" failed: ${result.error}`)
}

Integration

MCP Servers — tool sources exposed over the Model Context Protocol
MCP Client — connects to MCP servers and surfaces their tools
SystemActions — built-in system-level actions available as tools

Tools

On this page