Tools reference

The MCP server exposes eleven tools. Ten are thin wrappers over the public REST API; the eleventh, buzzabout__ask, delegates to the AI assistant. Tool names are namespaced buzzabout__* to avoid collisions in hosts that connect multiple MCP servers.

All tools require auth (Connect Claude for OAuth, Headless agents for API key). buzzabout__ask requires OAuth specifically.

Datasets

search_query is a discriminated union — { type: "prompt", sources, search_query } for keyword search, or { type: "url", source_urls } for direct URL scraping. Optional parameters mirror POST /v1/datasets/{id}/runs (count, num_comments_per_post, date_range, country_code, language, enable_visual_recognition, enable_transcribing, content_analysis_actions).

Audience datasets

total_profile_count is optional on create_audience_dataset_run (default 850, range 1–2000). The tool intentionally trims the surface: no list_audience_datasets, no get_audience_dataset, no list-runs — those use cases are covered by buzzabout__ask conversationally.

Reads

Both default to scoping by all account-owned resources. Pass dataset_ids (resp. audience_dataset_ids) to narrow. Filters, sort, order, cursor, limit mirror the mentions / profiles REST endpoints.

Chat

chat_id is optional — pass it from a prior buzzabout__ask response to continue the same chat. Both chat_id and message_id are 27-char KSUIDs with no prefix. See the deep-dive for input shape, response shape, and how to expand references.

Pagination model

The five list_* tools (datasets, mentions, audience profiles — plus internal pagination on the others) 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 buzzabout__list_mentions and buzzabout__list_audience_profiles encode the sort dimension, so don't reuse a cursor across sort changes.

Polling async runs

buzzabout__create_dataset_run and buzzabout__create_audience_dataset_run return:

{
  "run_id": "dr_01H...",
  "status": "pending",
  "next_step": "Call buzzabout__get_dataset_run with this run_id to poll completion."
}

The host LLM polls buzzabout__get_dataset_run / buzzabout__get_audience_dataset_run until status.type is completed or failed. Each tool's response carries 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:

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

The code is stable — match on it. The message is for humans. status mirrors the HTTP status the equivalent REST call would return.