Tools

Tools are the actions ScalyClaw can take during a conversation. The LLM decides when and how to use them — it emits a structured tool call, the system executes it, and the result is fed back into the conversation before the LLM continues. This loop repeats until the LLM produces a final text response with no pending tool calls.

ScalyClaw ships with a large set of built-in tools covering code execution, memory, messaging, scheduling, agent management, file I/O, vault, configuration, and more. They are always available — no additional configuration required. MCP tools from connected servers are discovered automatically and work the same way.

Built-in Tools

Built-in tools are divided into two categories by how they execute: direct tools run inline on the Node process, and job tools are dispatched to a BullMQ worker queue. See the Tool Architecture section for the full routing table.

Direct Tools

Direct tools run synchronously in the Node process. They are fast, lightweight operations — SQLite queries, Redis reads/writes, in-memory lookups — where the overhead of a queue round-trip would be net negative.

Memory

Messaging

Agents

Scheduling

Vault

Models

Skills

Guards

Configuration

Usage

Queue and Process Management

File I/O

Context

Job Tools

Job tools are dispatched to BullMQ worker queues. The Node process enqueues a job and awaits the result asynchronously. This provides process isolation for arbitrary code execution, a separate concurrency domain for agent delegation, and the ability to scale workers independently.

Meta Tools (Job Management)

Meta tools let the LLM inspect and manage the jobs it has submitted, enabling patterns like fire-and-forget parallelism with later result collection.

Tool Call Example

When the LLM decides to use a tool, it emits a structured JSON object. ScalyClaw parses this, routes it to the correct execution target, and returns the result in the next turn.

// memory_store — persist a user preference
{
  "type": "tool_use",
  "id": "toolu_01XqR9",
  "name": "memory_store",
  "input": {
    "content": "User prefers responses in British English",
    "type": "preference",
    "confidence": 0.95
  }
}

// execute_code — run a quick calculation
{
  "type": "tool_use",
  "id": "toolu_02Yp7K",
  "name": "execute_code",
  "input": {
    "language": "js",
    "code": "const result = [1,2,3,4,5].reduce((a,b) => a+b, 0);\nconsole.log(result);"
  }
}

// schedule_recurrent_reminder — recurring daily reminder
{
  "type": "tool_use",
  "id": "toolu_03Zc1M",
  "name": "schedule_recurrent_reminder",
  "input": {
    "message": "Time to review your open tasks",
    "cron": "0 9 * * 1-5",
    "timezone": "Europe/London"
  }
}

MCP Tools

ScalyClaw supports the Model Context Protocol (MCP). Tools discovered from connected MCP servers are automatically added to the available tools list at startup and whenever a hot-reload signal is received. They appear alongside built-in tools with no special configuration required beyond registering the MCP server connection.

The LLM uses MCP tools exactly the same way it uses built-in tools — by name, with a structured input object. ScalyClaw handles schema discovery, input validation, and result forwarding transparently.

Tool Architecture

Not all tools need the same execution environment. The unified tool router in tool-impl.ts uses a TOOL_QUEUE map to decide where each tool runs before dispatching it. This keeps the routing logic in one place and makes it easy to add new tools without changing the orchestrator.

Routing Table

Simplified Routing Logic

// tool-impl.ts — TOOL_QUEUE map (simplified)
const TOOL_QUEUE: Map<string, "tools" | "agents" | null> = new Map([
  ["execute_command",            "tools"],    // → scalyclaw-tools (sandboxed worker)
  ["execute_skill",              "tools"],    // → scalyclaw-tools (skill runner)
  ["execute_code",               "tools"],    // → scalyclaw-tools (sandboxed worker)
  ["delegate_agent",             "agents"],   // → scalyclaw-agents (agent executor)
  // everything else → null → local executeTool()
]);

async function routeTool(call: ToolCall): Promise<ToolResult> {
  const queue = TOOL_QUEUE.get(call.name);

  if (queue === "tools") {
    return dispatchToQueue("tools", call);    // await BullMQ job result
  }
  if (queue === "agents") {
    return dispatchToQueue("agents", call);   // await BullMQ job result
  }
  // null → run inline in the Node process
  return executeTool(call);
}

Why the Split?

The split between worker-queued and locally-executed tools reflects two different concerns:

• Isolation and safety — execute_code and execute_command run arbitrary user-provided code and shell commands. Executing them inside the Node process could crash the orchestrator or expose internal state. The worker process provides a hard process boundary. If execution goes wrong, only the worker job fails — the Node is unaffected.
• Module loading — Skills are TypeScript/JavaScript modules loaded dynamically from Redis. The worker maintains the module cache so reloads are fast and the Node's runtime stays clean.
• Independent scaling — By routing code execution and agent delegation to separate queues, you can run more workers in high-throughput scenarios without touching the Node. Memory and scheduler operations are fast enough that the overhead of a queue round-trip would be net negative.
• Latency — Memory reads, memory writes, and vault lookups each complete in under 5 ms against a local SQLite database or Redis connection. Queueing them would add 10–50 ms of unnecessary overhead per tool call.

Agent Tool Scoping

Sub-agents have a restricted tool set compared to the main orchestrator. This prevents runaway recursion (agents cannot delegate further), limits scheduling access to the main channel, and keeps sub-agent scope focused on the task at hand.