bot/docs/plugins/agent-tools.md

summary, read_when, title

summary	read_when	title
Write agent tools in a plugin (schemas, optional tools, allowlists)	You want to add a new agent tool in a plugin You need to make a tool opt-in via allowlists	Plugin Agent Tools

Plugin agent tools

HanzoBot plugins can register agent tools (JSON‑schema functions) that are exposed to the LLM during agent runs. Tools can be required (always available) or optional (opt‑in).

Agent tools are configured under tools in the main config, or per‑agent under agents.list[].tools. The allowlist/denylist policy controls which tools the agent can call.

Basic tool

import { Type } from "@sinclair/typebox";

export default function (api) {
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({
      input: Type.String(),
    }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });
}

Optional tool (opt‑in)

Optional tools are never auto‑enabled. Users must add them to an agent allowlist.

export default function (api) {
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a local workflow",
      parameters: {
        type: "object",
        properties: {
          pipeline: { type: "string" },
        },
        required: ["pipeline"],
      },
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

Enable optional tools in agents.list[].tools.allow (or global tools.allow):

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // specific tool name
            "workflow", // plugin id (enables all tools from that plugin)
            "group:plugins", // all plugin tools
          ],
        },
      },
    ],
  },
}

Other config knobs that affect tool availability:

• Allowlists that only name plugin tools are treated as plugin opt-ins; core tools remain enabled unless you also include core tools or groups in the allowlist.
• tools.profile / agents.list[].tools.profile (base allowlist)
• tools.byProvider / agents.list[].tools.byProvider (provider‑specific allow/deny)
• tools.sandbox.tools.* (sandbox tool policy when sandboxed)

Rules + tips

• Tool names must not clash with core tool names; conflicting tools are skipped.
• Plugin ids used in allowlists must not clash with core tool names.
• Prefer optional: true for tools that trigger side effects or require extra binaries/credentials.