Tools reference

The MCP server exposes 15 tools, in three kinds:

• Research tools you drive — collect_mentions, get_run, detect_patterns, query, plus ingest_mention and get_save_mention_status for saving a directly linked post. You choose the search query, decide when to cluster, and ask your own questions of the result. The reasoning is yours.
• The assistant — ask → get_message → render. Hands the whole job to the buzzabout assistant instead. Use it for what the research tools do not cover: composing a written report or asset, setting up a tracking agent, saving an insight.
• Lookups — what the account already has.

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

The research flow

list_collections    → does this topic already exist?
collect_mentions    → if not, collect it (you write the query)
get_run             → wait; long-polls ~45s per call
detect_patterns     → cluster the collection into its themes
get_run             → wait again
query               → read the themes, their counts, and the posts inside them

The deliverable is the answer. A search query, an estimate, a run id or a cluster list is a step, never the end.

buzzabout__collect_mentions

Collects public posts for a topic. You write the search query — keep it short and broad: six words at most, at most one OR and one AND. Search for the subject, not for the question you are asking about it.

Before collection spending, the server runs a billed research preview and checks how much conversation matches, whether the results really come from the platforms you asked for, and whether they look on-topic. If it is healthy the collection starts and you get a run id. If it is decisively thin, collection does not start or spend and you get the signals plus a sample back. The preview still has its per-source charge; broadening the query and calling again creates another billed preview.

{
  "started": true,
  "collection_id": "ds_…",
  "run_id": "dr_…",
  "signals": { "estimated_matches": 28200, "sample_posts": 16, "on_topic_fraction": 0.62 },
  "next": "Wait with buzzabout__get_run(…)"
}

on_topic_fraction is a rough signal over a handful of search snippets, not a verdict — low is worth a glance at the sample, not an automatic rewrite.

buzzabout__collect_audience

Profiles the authors behind a mentions collection — demographics, interests, brand affinity. Takes collection_id, optional name and count. Read the result with query(subject: "audience_profiles").

buzzabout__ingest_mention

Save one public post by its direct URL. No research preview is needed for an explicit save request. If a user only pastes a link and the intent is unclear, ask what they want to do before saving it.

Supported formats are Instagram /p/ and /reel/, TikTok /@user/video/…, X/Twitter /status/…, Reddit submission /comments/… and redd.it/…, LinkedIn activity/URN-bearing post URLs, and YouTube /watch?v=…. Profiles, feeds, arbitrary websites, Facebook and redirect-dependent short links are not accepted.

Returns immediately after queuing, not after scraping or analysis:

{
  "run_id": "dr_…",
  "collection_id": "col_…",
  "source": "youtube",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "post_id": null,
  "saved": false,
  "phase": "queued",
  "status": { "type": "pending", "steps": [] }
}

The post becomes available in the collection as soon as scraping and saving finish; content analysis continues in the background. Repeating the request can re-scrape, re-analyze and overwrite the post, but does not create duplicate membership in the same collection. Normal collection processing charges apply; retries are not guaranteed to be free.

buzzabout__get_save_mention_status

Read the current status without starting another save. Pass the run_id returned by ingest_mention. Alternatively, pass source and post_id to find the latest visible save operation, optionally scoped to collection_id.

Returns the same shape as ingest_mention, updated with progress:

Use saved as the authority for whether the post is persisted. A post-reference lookup with no matching save operation returns null; an unknown or inaccessible run_id returns an error. This is a current status read, not the long-polling research get_run tool.

buzzabout__detect_patterns

Clusters a collection into the themes actually present in it, each with its posts and a count.

Run this before drawing conclusions. Reading a sample yourself surfaces whatever caught your eye; clustering the whole collection tells you what is there in proportion, and the gap between a large cluster and a small one is usually the finding.

Refuses while a collection is still filling — clustering half of one describes whatever arrived first and reads like a finished answer.

buzzabout__query

Ask a question about collected data and get a table back. Counts, breakdowns, rankings, time series and text retrieval, over mentions (posts and comments) or audience_profiles (the authors).

pseudo_sql is a sketch, not real SQL: table and column names need not exist and you do not need to know the schema. The server writes and runs the real query. That AI planner consumes charged inference, including when all queried rows were already collected. The final provider-cost-based USD charge is projected into credits at the account rate; do not estimate it as a flat per-call credit fee.

Anything the schema cannot answer comes back in unsupported alongside whatever results were still possible — read it and adjust rather than repeating the request. The SQL that ran is returned too, so you can see how the question was interpreted.

This is also how you read detected themes: ask for the pattern themes with the number of posts in each, then for the posts inside the ones that matter.

buzzabout__get_run

Waits for a collection, audience or pattern-detection run. Long-polls — one call holds up to ~45s and returns the moment the run settles. If it comes back still working, call it again immediately; do not add a delay. Runs take ~2–3 minutes.

Takes run_id, kind (mentions | audience | patterns) and collection_id for the first two.

The assistant: ask → get_message → render

Use for what the research tools do not cover — a written report or asset, setting up a tracking agent, saving an insight, or a request too open-ended to serve with retrieval alone.

buzzabout__ask

Asynchronous — returns { chat_id, message_id } immediately. Each new Ask turn consumes token-priced inference and can start separately charged data work. Polling the existing message does not start another turn.

buzzabout__get_message

Takes chat_id and message_id. Long-polls up to ~45s; call it again straight away if it returns still working. Do not call ask again to check progress — that starts a second turn.

Returns blocks in order. Walk them: render: true → call render; render: false → relay its text yourself.

buzzabout__render

Takes message_id and block_id. Only for render: true blocks — calling it on any other returns an error and the host shows an empty card.

Lookups

buzzabout__list_collections

kind (mentions | audience), limit, cursor. Check here first — if the topic is already collected there is no need to collect it again.

buzzabout__list_mentions

A plain filtered, sorted, cursor-paginated list of mentions. Free raw read — no inference, unlike query — so prefer it when you want rows rather than an answer. Supports dataset_ids, sources, sort, order, filters, cursor, limit.

Tracking agents

Tracking agents are set up through charged ask turns; these tools only read what exists. Paid collection still requires available balance.

Account

Pagination

list_* tools return { "content": [ … ], "cursor": "eyJ…=" }. Pass the cursor back to fetch the next page; null means the end. Cursors encode the sort dimension, so don't reuse one across a sort change.

query does not paginate — it caps at limit and sets truncated. When it does, ask an aggregate question rather than paging through rows one at a time.

Errors

Tools return errors as data, not exceptions:

{
  "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.