buzzabout__ask

buzzabout__ask is the chat tool — a thin bridge between an MCP host and the Buzzabout AI assistant. Hand it a natural-language prompt; it streams the response off the assistant, aggregates the markdown text, collects the structured side-effects (datasets created, audience datasets created, research previews generated, patterns detected), and returns one tool result.

buzzabout__ask({ prompt, chat_id? }) → { chat_id, message_id, text, references }

Auth

buzzabout__ask requires the OAuth/JWT auth path. API-key callers get a structured forbidden error — the AI assistant chat backend operates on user identity, and an API key isn't bound to one.

{
  "error": {
    "code": "forbidden",
    "message": "buzzabout__ask requires user JWT auth; api-key callers cannot impersonate a user against the AI assistant.",
    "status": 403
  }
}

See Connect Claude for the OAuth install.

Input

There's no built-in chat discovery — host LLMs only have a chat_id when a prior buzzabout__ask call returned one in the same host session. Resuming a web-app-started chat is a v1.5 follow-up.

Output

{
  "chat_id": "3DR9jYTuJTQeog0FseKCWE2fyLe",
  "message_id": "3DR9jZ8VfJ1bGqK7HnQpW4tXcMd",
  "text": "## Top three hooks across the cold-brew dataset...",
  "references": [
    { "type": "dataset", "id": "ds_01H..." },
    { "type": "audience_dataset", "id": "ad_01H..." },
    { "type": "research_preview", "id": "rp_01H..." },
    { "type": "pattern", "id": "pat_01H..." }
  ]
}

The assistant runs in markdown mode when called via MCP. Charts, tables, and lists come back as plain markdown — no React components, no custom widgets.

Reference types

Every references[] entry is a { type, id } pair you can use to dereference the resource the assistant produced or referenced.

References are deduped — the same (type, id) only appears once per response.

Behaviour notes

• buzzabout__ask aggregates. The MCP server consumes the assistant's SSE stream internally and returns one result when the stream closes. There's no SSE pass-through to the host LLM.
• A reply can take 5–30 seconds for short prompts, longer if the assistant kicks off a dataset run or pattern detection. Configure your MCP host's tool timeout to ≥ 600 seconds.
• Chats created via MCP appear in the web app under the same chats list as user-created chats — there's no source: mcp separation.

Example session

A typical multi-turn agent loop:

1. host: buzzabout__ask({ prompt: "Find the top hooks in cold-brew TikToks this week" })
   → { chat_id: "3DR9jYTuJTQeog0FseKCWE2fyLe", text: "...", references: [{ type: "dataset", id: "ds_01H..." }] }

2. host: buzzabout__list_mentions({ dataset_ids: ["ds_01H..."], sort: "engagement_rate", limit: 5 })
   → { content: [...], cursor: null }

3. host: buzzabout__ask({
       chat_id: "3DR9jYTuJTQeog0FseKCWE2fyLe",
       prompt: "Summarise the top 5 by hook framing"
     })
   → { chat_id: "3DR9jYTuJTQeog0FseKCWE2fyLe", text: "...", references: [...] }

Note step 1 returned a dataset reference — the assistant created a dataset and ran it, then summarised. Step 2 used that id to read the mentions directly via REST-mirror. Step 3 continued the same chat by passing chat_id back, so the assistant retained context.

Errors