Tools reference

The MCP server exposes 32 tools across 9 groups. Each tool's description in the live tools/list response opens with a [<Group>] prefix so in-host pickers stay scannable even before any filtering.

All tools require auth — see Authentication. The single exception is buzzabout__ask, which requires OAuth/JWT and rejects api-key callers with a forbidden error.

Group: datasets (8)

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.

Group: mentions (1)

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

Group: audience_datasets (8)

total_profile_count defaults to 850 (range 1–2000) on create_audience_dataset_run.

Group: audience_profiles (1)

Mirrors POST /v1/audience_profiles. Defaults to scoping by all account-owned audience datasets.

Group: tracking_agents (8)

PATCH is deliberately not exposed via MCP — uncommon admin op; do it via the REST endpoint.

Group: patterns (4)

Group: custom_parameters (9)

scope stays a tagged union with one variant in v1 so additional scopes can land additively.

Group: chat (3)

buzzabout__ask — the assistant tool

Hand a prompt to the AI assistant; get a markdown reply, an optional chat_id to continue the conversation, and a references[] array of typed pointers into buzzabout resources.

Input:

Output:

{
  "chat_id": "01H...",
  "message_id": "01H...",
  "text": "...markdown body with inline [post links](post:reddit:t3_1...)...",
  "references": [
    { "type": "pattern", "id": "pt_..." },
    { "type": "dataset", "id": "ds_..." }
  ]
}

The text is markdown; inline post citations use the [label](post:source:id) scheme. references[] is a flat list of typed pointers — see Reference types for the six types and their resolution endpoints.

Pass the returned chat_id back as the chat_id argument to continue the same chat across turns.

Group: account (2)

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 async runs

create_dataset_run, create_audience_dataset_run, create_pattern_detection, trigger_custom_parameter_run, and trigger_tracking_agent_run all return:

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

Poll the corresponding get_*_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.

Next steps

• Use in your agent — wire MCP into Claude, Cursor, ChatGPT, or your own SDK.
• Reference types — how references[] and inline post links work.
• API reference — REST equivalents of each tool.