AI Tools Hook

Use this hook to give the Broadcast AI assistant a new tool. When a person asks a question that your tool can answer, the assistant can call it.

How it works

Your manifest describes the tool. The assistant reads the description to decide when to use it, so write it for a reader who has never seen your plugin.

Full example: find tags

manifest.json:

{
  "id": "local.tag-helper",
  "name": "Tag helper",
  "version": "1.0.0",
  "requires": { "broadcast": ">=3.0.0 <4.0.0", "pluginApi": "1" },
  "permissions": {
    "tags": "read"
  },
  "hooks": {
    "aiTools": [
      {
        "name": "find_tags",
        "description": "Finds the tags in this channel that contain a word.",
        "readOnly": true,
        "input_schema": {
          "type": "object",
          "properties": {
            "word": { "type": "string", "description": "The word to look for" }
          },
          "required": ["word"]
        }
      }
    ]
  }
}

dist/main.js:

export default definePlugin({
  aiTools: {
    async find_tags({ input }, ctx) {
      const word = String(input.word ?? "").toLowerCase();
      const tags = await ctx.broadcast.tags.list();
      return { tags: tags.filter((tag) => tag.toLowerCase().includes(word)) };
    },
  },
});

The manifest fields

What you get and return

You get this. The tool’s arguments are in input:

{ "name": "find_tags", "input": { "word": "new" } }

Return any JSON value. The assistant reads it and answers the person.

Who can use the tool

The tool appears only in channels where the plugin is on. It appears only for people who hold every data permission that the plugin holds. For example, a person who may not read subscribers does not get the tools of a plugin that reads subscribers.

Common mistakes

You write a short description. “Tags” tells the assistant nothing. Say what the tool does and when it is useful.

You trust the input. The input comes from an AI model. It can be missing or have an odd form. Check it.

You return too much. Return only what answers the question, and no more personal data than is needed.

You mark a tool readOnly when it writes. This removes the confirmation step, so people can lose the chance to say no.