Tool Registry

The agent runtime uses an MCP-first, API-fallback architecture. External data sources are accessed through Model Context Protocol (MCP) servers when available, with custom API wrappers as internal tools for everything else. All tool I/O passes through the AI Firewall.

Architecture

Company Runtime
  │
  ├── ToolRegistry (central dispatcher)
  │     ├── Internal tools (43 registered)
  │     └── MCP tools (auto-discovered)
  │
  └── MCPClientHub
        ├── Hyperliquid MCP  (~27 tools)
        ├── Hive Intel MCP   (351 tools)
        ├── EVM MCP          (22 tools)
        └── DeFi Trading MCP (25+ tools)

MCP Servers

Four MCP servers are configured in the MCPClientHub. Each server is tagged with the categories it serves:

When the runtime boots, MCPClientHub.initialize(companyCategory) filters to only the servers relevant to that company’s category and connects via the MCP SDK:

const relevantServers = MCP_SERVERS.filter((s) =>
  s.categories.includes(companyCategory),
);

Each MCP tool is assigned a prefix to prevent name collisions: hl_ for Hyperliquid, hive_ for Hive Intel, evm_ for EVM, and dex_ for DeFi Trading.

ToolDefinition Interface

Every tool — internal or MCP-bridged — implements the ToolDefinition interface:

interface ToolDefinition {
  id: string;           // Unique tool ID (OpenAI function name)
  name: string;         // Human-readable display name
  description: string;  // LLM instruction for when to use
  category: ToolCategory;
  tier: ToolTier;
  costMicroUsdc: bigint; // Cost per call in micro-USDC
  parameters: ToolParameters; // JSON Schema (OpenAI format)
  execute: (params, context?) => Promise<unknown>;
  timeoutMs?: number;   // Default: 30,000ms
}

Tool Categories

Tools are organized into 5 functional categories. Agents only receive tools matching their allowed skill categories:

Tool Tiers

Each tool has a pricing tier that determines access level and cost:

MCP tools default to STANDARD tier at 5,000 micro-USDC ($0.005) per call.

Internal Tools (43)

The tool-implementations.ts file registers 43+ internal tools across all categories:

Market Data

Social

Chain

Security

Service (A2A)

AI Firewall

All tool inputs and outputs pass through the 3-layer AI Firewall (sanitizeContent()):

1. Pattern matching — 32 regex patterns detect prompt injection attempts
2. Content classification — classifies input as safe/suspicious/malicious
3. Output sanitization — strips potentially harmful content from tool responses

The firewall runs in under 1ms and is applied to every ToolRegistry.executeTool() call.

MCP Caching

MCP tool responses are cached in ScrapeCache with tool-specific TTLs:

Timeout Protection

Every tool execution is wrapped in a timeout (default 30 seconds). If a tool exceeds its timeoutMs, the call is rejected and the error is logged:

const { result, durationMs } = await registry.executeTool(
  'defi_yield_pools',
  { chain: 'base', minApy: 5 },
  agentContext,
);

Category-Aware Loading

The full tool loading sequence during runtime initialization:

1. registerDefaultTools() — register all 43+ internal tools
2. initializeMCP(companyCategory) — connect category-relevant MCP servers
3. MCP tools auto-discovered via listTools() and bridged into ToolRegistry
4. getToolsForAgent(allowedCategories) — filter by agent’s skill categories
5. toOpenAITools(tools) — convert to OpenAI function calling format for LLM