Tools reference

The MCP server exposes 15 tools. They fall into two kinds:

• The assistant flow — ask → get_message → render. This is where the work happens. ask hands a prompt to the buzzabout assistant, which writes the search query, previews it, collects posts, profiles audiences, detects patterns, and analyses — then returns the answer as text or an interactive widget.
• Read-only lookups — list and fetch the datasets, runs, mentions, audience profiles, and tracking agents the account already has.

All tools require auth — see Authentication. Both x-api-key and OAuth/JWT callers can use every tool, including ask.

The assistant flow: ask → get_message → render

ask is asynchronous — research can run for minutes, past a host's tool-call timeout — so it returns immediately with an id, and you poll get_message for the answer.

buzzabout__ask

Hand a prompt to the assistant. Returns right away; does not wait for the answer.

{
  "chat_id": "01H...",
  "message_id": "01H...",
  "status": "working"
}

Keep the chat_id to continue the conversation; pass chat_id + message_id to get_message to retrieve the answer.

buzzabout__get_message

Poll for the answer to an ask. Long-polls — one call holds for up to ~45s, returning the moment the turn settles, so you call it back-to-back rather than waiting between calls.

{
  "chat_id": "01H...",
  "message_id": "01H...",
  "status": "working",          // or "completed" / "failed"
  "stop_reason": null,          // non-null once finished
  "blocks": [
    { "block_id": "b1", "type": "text", "render": false, "text": "...markdown..." },
    { "block_id": "b2", "type": "openui", "render": true }
  ]
}

blocks arrive only once the turn settles. Walk them in order: a render: true block is an interactive widget — call render; a render: false block already carries its text — relay it to the user as-is.

If a run is genuinely long and you're low on tool calls, stop polling and tell the user — the chat is saved, and you (or they, next turn) can resume with the same chat_id + message_id.

buzzabout__render

Render one render: true block as an interactive MCP App widget (hosts that support the io.modelcontextprotocol/ui extension). Bound to the ui://buzzabout/message UI resource.

Returns the block's OpenUI as structuredContent the host renders natively. Only call it on render: true blocks — a render: false block has no widget to draw.

Read-only lookups

These look up entities the account already owns — they never create or charge. All list_* tools are cursor-paginated (see below).

Datasets

Audience

list_audience_profiles defaults to all account-owned audience datasets. Mirrors POST /v1/audience_profiles.

Mentions

Defaults to all account-owned datasets; pass dataset_ids to narrow. Filters, sort, order, cursor, limit mirror the REST mentions endpoint.

Patterns

Pattern detection is started through ask; this read polls a run's status. The pattern's content flows back through the assistant.

Tracking agents

Account

Pagination model

All list_* tools return:

{
  "content": [ /* rows */ ],
  "cursor": "eyJ...="
}

Pass the cursor back as the cursor argument to fetch the next page. A null cursor means you've hit the end. Cursors on filtered list endpoints (mentions, audience profiles) encode the sort dimension, so don't reuse a cursor across sort changes.

Polling runs

Two things to poll, both covered above:

• An ask turn → get_message (long-polls; settles at stop_reason non-null).

• An existing run's status → the matching get_*_run (get_dataset_run, get_audience_dataset_run, get_pattern_detection_run) until status.type is completed or failed. These carry the same status envelope as the REST API:

  {
    "status": {
      "type": "working",
      "steps": [ { "name": "scraping", "completed_at": 1714564890 } ]
    }
  }

Error shape

Tool errors come back as a JSON object with an error field — same error_code taxonomy as the REST API:

{
  "error": {
    "code": "dataset_not_found",
    "message": "Dataset not found",
    "status": 404
  }
}

Match on code (stable); show message to humans. status mirrors the HTTP status the equivalent REST call would return.

Next steps

• Use in your agent — wire MCP into Claude, Claude Code, Codex, Cursor, ChatGPT, or your own SDK.
• Reference types — how references[] and inline post links resolve.
• API reference — the REST surface, including programmatic CRUD.