registerTool

The global tool registry allows you to register custom tools by name. Once registered, agents can reference them as strings in their tools configuration, just like built-in tools.

import { registerTool, defineTool, createAgent } from "@comma-agents/core";
import { z } from "zod";

const fetchTool = defineTool({
  description: "Fetch a URL and return its text content.",
  parameters: z.object({ url: z.string().url() }),
  execute: async ({ url }) => ({ output: await fetch(url).then(r => r.text()) }),
});

registerTool("fetch", fetchTool);

// Now agents can reference "fetch" by name alongside built-in tools
const agent = createAgent({
  name: "researcher",
  model: "openai/gpt-4o",
  tools: ["read_file", "run_command", "fetch"],
});

Resolution Order

When an agent resolves a tool name, the following order is checked:

1. Global tool registry — custom tools registered via registerTool()
2. Built-in tools — read_file, list_directory, search_files, create_file, write_file, edit_file, delete_file, move_file, apply_patch, run_command, webfetch, and the todo_* tools.
3. Error — unknown tool name throws a StrategyValidationError

Custom registry tools shadow built-in tools of the same name.

registerTool

Register a custom tool with the global tool registry. Registered tools can be referenced by name in agent definitions.

If the name matches a built-in tool or a previously registered tool, a warning is logged. The new registration takes effect immediately.

registerTool("myTool", myToolDefinition);

unregisterTool

Remove a previously registered custom tool. Returns true if the tool was registered and removed. Built-in tools cannot be unregistered.

const removed = unregisterTool("myTool"); // true

getRegisteredToolNames

Get the list of currently registered custom tool names. Does not include built-in tools.

const names = getRegisteredToolNames(); // ["fetch", "myTool"]

resetToolRegistry

Reset the global tool registry to empty state. Primarily useful in tests.

resetToolRegistry();

Overriding Built-in Tools

To replace a built-in tool with a custom implementation, register a tool with the same name:

import { defineTool, registerTool } from "@comma-agents/core";
import { z } from "zod";

const customReadFile = defineTool({
  description: "Custom read_file tool with different behavior.",
  parameters: z.object({ path: z.string() }),
  execute: async ({ path }) => {
    // custom logic
    return { output: "..." };
  },
});

// Shadows the built-in "read_file" tool — a warning is logged
registerTool("read_file", customReadFile);

All agents referencing "read_file" will now use the custom implementation.