Agent tools

Agent tools are actions the AI can invoke during a run. A plugin registers a tool through api.registerTool(...); the runtime exposes it to the model, validates input against your schema, calls your execute() handler, and returns the result to the model.

Tools are registered from a plugin’s register function. If you have not built a plugin yet, start with Write your first plugin — this page goes deeper on the tool surface itself.

The tool shape

The object you pass to api.registerTool(...) is an AnyAgentTool. The fields that matter for a typical tool are:

Field	Type	Notes
`name`	`string`	The tool name the model sees. Use a namespaced, unique name.
`description`	`string`	The model reads this to decide when to call the tool. Be specific.
`parameters`	TypeBox schema	Input schema (`Type.Object({ ... })`).
`execute`	`(id, params) => Promise<result>`	Your handler. Returns a content result.

There is no ToolDefinition, no inputSchema, and no run() — those are not part of the WednesdayAI surface. The real type is AnyAgentTool, re-exported from openclaw/plugin-sdk.

Defining a tool

import { Type } from "@sinclair/typebox";
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";

export default function register(api: OpenClawPluginApi): void {
  api.registerTool({
    name: "fetch_url",
    description: "Fetch the contents of a URL and return the text.",
    parameters: Type.Object({
      url: Type.String({ description: "The URL to fetch." }),
      timeoutMs: Type.Optional(
        Type.Number({ description: "Timeout in milliseconds. Default: 5000." }),
      ),
    }),
    async execute(_id, params) {
      const url = params.url as string;
      const timeoutMs = (params.timeoutMs as number | undefined) ?? 5000;
      const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
      if (!res.ok) {
        return {
          content: [{ type: "text", text: `HTTP ${res.status} from ${url}` }],
        };
      }
      const text = await res.text();
      return { content: [{ type: "text", text }] };
    },
  });
}

The `execute` signature

execute(id, params) receives:

id — the tool-call id assigned by the runtime. Most tools ignore it (_id).
params — the validated input object matching your parameters schema.

The return value

execute returns a content result. The common shape is a single text block:

return { content: [{ type: "text", text: "result here" }] };

The content array may include text and image blocks. For JSON payloads, use the jsonResult(...) helper from the SDK, which stringifies the payload into a text block and attaches structured details:

import { jsonResult } from "openclaw/plugin-sdk";

async execute(_id, params) {
  return jsonResult({ ok: true, query: params.query });
}

Reading parameters safely

Model-supplied params are untrusted. The SDK exposes typed readers that coerce and validate input and throw a clear error on bad values:

import { readStringParam, readNumberParam } from "openclaw/plugin-sdk";

async execute(_id, params) {
  const query = readStringParam(params, "query", { required: true });
  const limit = readNumberParam(params, "limit", { integer: true }) ?? 5;
  // ...
}

These readers also accept snake_case variants of camelCase keys, so timeoutMs resolves from either timeoutMs or timeout_ms.

Schema rules

These constraints apply to every tool parameters schema:

Rule	Why
No `Type.Union`	Structural unions confuse model tool use. Use separate fields or tools.
No `anyOf` / `oneOf` / `allOf`	Same reason.
Use `Type.Optional(...)` not `T \| null`	`null` is not the WednesdayAI convention.
Use `stringEnum` / `optionalStringEnum` for enums	These produce a `Type.Unsafe` enum the validators accept.
Never use `format` as a raw property name	Some validators reject it.

stringEnum and optionalStringEnum are exported from openclaw/plugin-sdk:

import { Type } from "@sinclair/typebox";
import { stringEnum } from "openclaw/plugin-sdk";

const parameters = Type.Object({
  mode: stringEnum(["fast", "thorough"], { description: "Search mode." }),
});

Optional tools (opt-in)

By default, a registered tool is available to all agents. If your tool makes outbound requests, uses a paid API, or has side effects, register it as optional so operators opt in explicitly:

api.registerTool(
  {
    name: "workflow_tool",
    description: "Run a local workflow.",
    parameters: Type.Object({ pipeline: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.pipeline as string }] };
    },
  },
  { optional: true },
);

Optional tools are never auto-enabled. Users enable them in their config under tools.allow (global) or agents.list[].tools.allow (per-agent):

{
  tools: {
    allow: [
      "workflow_tool", // a specific tool name
      "my-plugin", // a plugin id — enables all tools from that plugin
      "group:plugins", // all plugin tools
    ],
  },
}

An allowlist that names only plugin tools is treated as plugin opt-in: core tools stay enabled unless you also list core tools or groups.

Owner-only tools

Set ownerOnly: true on the tool object to restrict execution to owner senders. The runtime wraps non-owner calls so they fail with a restriction error before execute runs.

api.registerTool({
  name: "danger_action",
  description: "Owner-only privileged action.",
  parameters: Type.Object({}),
  ownerOnly: true,
  async execute() {
    return { content: [{ type: "text", text: "done" }] };
  },
});

Tool factory context

The full set of fields available in a tool factory context (OpenClawPluginToolContext):

Field	Type	Description
`config`	`OpenClawConfig \| undefined`	The resolved gateway config
`workspaceDir`	`string \| undefined`	Workspace directory path for the current agent
`agentDir`	`string \| undefined`	Agent-specific directory path
`agentId`	`string \| undefined`	The agent id that is running
`sessionKey`	`string \| undefined`	Unique session key (e.g. `agent:id:telegram:dm:123`)
`sessionId`	`string \| undefined`	Ephemeral session UUID — regenerated on `/new` and `/reset`; use for per-conversation isolation
`messageChannel`	`string \| undefined`	The channel surface (`"telegram"`, `"discord"`, `"whatsapp"`, etc.)
`agentAccountId`	`string \| undefined`	The channel account id the message arrived on
`requesterSenderId`	`string \| undefined`	Trusted sender id from inbound context (runtime-provided, not tool args)
`senderIsOwner`	`boolean \| undefined`	Whether the trusted sender is an owner
`sandboxed`	`boolean \| undefined`	Whether the gateway is running in sandbox mode

Tool factories

Instead of a static tool, you can pass a factory that receives per-invocation context (agent id, session key, workspace dir, sender identity) and returns a tool, an array of tools, or nothing:

api.registerTool((ctx) => {
  if (!ctx.agentId) return undefined;
  return {
    name: "scoped_tool",
    description: "A tool scoped to the current agent.",
    parameters: Type.Object({}),
    async execute() {
      return { content: [{ type: "text", text: `agent ${ctx.agentId}` }] };
    },
  };
});

Naming and conflicts

Tool names are not deduplicated at registration time. Two tools sharing a name will both register; runtime resolution order decides which is called. Use a unique, namespaced name (for example my-plugin_fetch_url).
A plugin tool name must not clash with a core tool name — conflicting tools are skipped.

Testing tools

import { describe, expect, it } from "vitest";
import { Type } from "@sinclair/typebox";

it("returns text content", async () => {
  let captured: any;
  const api: any = { registerTool: (tool: any) => (captured = tool) };
  register(api);

  const result = await captured.execute("call-1", { url: "https://example.com" });
  expect(result.content[0].type).toBe("text");
});

pnpm --filter @wednesdayai/my-plugin test:fast

Testing the real tool pipeline

The fake-api approach above unit-tests execute() in isolation. To test the pipeline the gateway actually runs — plugin discovery, factory resolution, allowlist filtering, and the model-facing tool definition — import the testing seam:

import {
  createEmptyPluginRegistry,
  loadOpenClawPlugins,
  resolvePluginTools,
  setActivePluginRegistry,
  toToolDefinitions,
} from "wednesdayai/plugin-sdk/testing";
// "openclaw/plugin-sdk/testing" is the compatible spelling.

The subpath is supported for test code only — never import it from production plugin code, and it is never loaded by the runtime loader. (This is a deliberate divergence from upstream openclaw, which keeps its testing barrel repo-local.) Three steps:

Discovery — loadOpenClawPlugins({ cache: false, workspaceDir, config }) with explicit plugins.enabled: true, plugins.allow, and plugins.load.paths pointing at fixture plugin files (a .cjs entry plus an openclaw.plugin.json manifest). Returns the real plugin registry.
Resolution + filtering — resolvePluginTools({ context }) invokes each registered tool factory and applies runToolAllowlist (and the optional-tool allow policy). One documented quirk: entries registered as bare factories carry no tool names up front, so a runToolAllowlist pre-filter skips them even when their resolved tool name matches — register tools with names if you rely on that filter.
Adaptation — toToolDefinitions(tools) produces the model-facing definitions: label falls back to name when unset, thrown errors become structured error results, and execute(toolCallId, params, signal, onUpdate) passes the AbortSignal as the third argument — never a host-context object.

loadOpenClawPlugins activates the global plugin registry. Reset it between tests so suites stay order-independent:

import { afterEach } from "vitest";

afterEach(() => {
  setActivePluginRegistry(createEmptyPluginRegistry());
});

PluginLoadOptions, PluginRegistry, PluginToolRegistration, and HookContext are exported as types for annotating fixtures.

Best practices

Single responsibility — one tool per well-defined action.
Clear descriptions — the model chooses tools from the description; be specific about what and when.
Validate input — use the SDK param readers; never trust raw model output.
Return helpful errors — return a text result describing the problem rather than throwing for expected failures.
Mark side-effecting tools optional — give operators explicit control.

What’s next

Write your first plugin — end-to-end worked example
Plugin SDK reference — the full exported surface
Hooks — lifecycle callbacks via api.on(...)

Getting started

Extension points

Channel references

SDK reference

Contributing

Core concepts (developer)

More plugins

Developer reference

Prompt templates

Shohin

Agent tools

Agent tools

The tool shape

Defining a tool

The `execute` signature

The return value

Reading parameters safely

Schema rules

Optional tools (opt-in)

Owner-only tools

Tool factory context

Tool factories

Naming and conflicts

Testing tools

Testing the real tool pipeline

Best practices

What’s next

​Agent tools

​The tool shape

​Defining a tool

​The execute signature

​The return value

​Reading parameters safely

​Schema rules

​Optional tools (opt-in)

​Owner-only tools

​Tool factory context

​Tool factories

​Naming and conflicts

​Testing tools

​Testing the real tool pipeline

​Best practices

​What’s next

Agent tools

The tool shape

Defining a tool

The `execute` signature

The return value

Reading parameters safely

Schema rules

Optional tools (opt-in)

Owner-only tools

Tool factory context

Tool factories

Naming and conflicts

Testing tools

Testing the real tool pipeline

Best practices

What’s next