Skip to content

Bundle Tools — MCP Tool Reference

A Bundle binds one Project, one Questionnaire, and a selected subset of that Questionnaire's Campaigns (plus an option to include ad-hoc surveys with no Campaign) to exactly one linear Bronze → Silver → Gold dataset chain. These tools manage the Bundle itself and its quality story; see Dataset Tools for the Bundle-scoped stage operations (extract, code + weight, refine, export).

create_bundle

Create a pipeline Bundle.

Parameter Type Required Default Description
name string Yes — Bundle name
project_id string Yes — Owning project (write access required)
questionnaire_id string Yes — Questionnaire whose completed surveys feed Bronze
campaign_ids string[] No [] Campaign subset to include (empty = none until set)
include_ad_hoc boolean No false Also include completed surveys with no campaign

Returns: { bundle_id, name }

list_bundles

List pipeline Bundles, optionally filtered to one project.

Parameter Type Required Default Description
project_id string No — Restrict to Bundles owned by this project

Returns:

{
  "items": [
    {
      "id": "...",
      "name": "Wave 1",
      "project_id": "...",
      "questionnaire_id": "...",
      "campaign_ids": ["..."],
      "include_ad_hoc": false,
      "chain": {
        "bronze": {"dataset_id": "...", "status": "ready"},
        "silver": {"dataset_id": "...", "status": "processing"}
      }
    }
  ],
  "count": 1
}

chain keys are the stages that have a dataset (bronze/silver/gold); a stage with no dataset yet is simply absent — treat it as missing.

clone_bundle

Deep-copy a Bundle's ready datasets and recipes into an independent variant.

Parameter Type Required Default Description
bundle_id string Yes — Source Bundle
name string No "{source} (copy)" Name for the clone

Returns: { bundle_id, cloned_stages } — cloned_stages lists which stages (bronze/silver/gold) had a ready dataset to copy.

The clone starts from a byte-identical copy of each ready stage and carries the same stage recipes (coding config, accepted categories, weighting targets, refine field specs), so it can be re-derived independently — e.g. with different weighting targets — without touching the original Bundle. This is how you compare variants (different weighting, different refinement) of the same raw extraction.

delete_bundle

Delete a Bundle and its dataset chain.

Parameter Type Required Default Description
bundle_id string Yes — Bundle to delete

Returns: { success: true }

Deletion is soft — the Bundle and its chain datasets are marked deleted immediately; their underlying data files are cleaned up by a background maintenance process shortly after.

Quality Tools

Quality is measured at the Bundle, not on individual datasets. Measures 2 and 3 grade against the Bundle's re-assignable current Strategy (current_strategy_id) — assign one before expecting them to be measured.

get_bundle_quality

The Bundle's four-measure quality story in one call:

  1. Pool vs intent — each campaign's respondent pool graded against the strategy that generated it (per-campaign entries; manual pools and ad-hoc collection report not_measurable with a reason)
  2. Fielded (Bronze) vs current Strategy — who actually answered, with a per-campaign breakdown
  3. Weighted (Silver) vs current Strategy — what weighting corrected
  4. Response quality — entropy, straightlining, Cronbach's alpha, acquiescence, non-response (see the Quality Metrics Reference)
Parameter Type Required Default Description
bundle_id string Yes — Bundle UUID

Returns: { quality: {...} } — the four measures plus chain/strategy context. Each measure carries a state (measured, not_measurable, no_strategy, not_derived, processing, invalidated, error) with a reason, so one unmeasurable or failing measure never hides the others. Measured payloads include overall score, composite error, and per-factor deviation analysis.

compare_bundle_quality

Bronze-vs-Silver representativeness comparison for the Bundle's chain, graded against the Bundle's current Strategy — the measure of what weighting bought you.

Parameter Type Required Default Description
bundle_id string Yes — Bundle UUID

Returns: { comparison: {...} } with per-factor and overall improvement. Both the Bronze and Silver must be ready; otherwise the call returns a validation error.

assign_bundle_strategy

Assign (or clear) the Bundle's current Sampling Strategy — the benchmark measures 2 and 3 grade against. Requires manager permissions and an identified user (service-token-only callers are rejected); assigning a strategy also requires access to the strategy's own project.

Parameter Type Required Default Description
bundle_id string Yes — Bundle UUID
strategy_id string No null Strategy to assign; null clears the assignment

Returns: { bundle_id, strategy_id, strategy_name }

To advance a strategy with reality-grounded outcome factors (e.g. political preference from the survey responses plus an external benchmark), use advance_sampling_strategy — it clones the strategy (the original is never edited) and the clone can then be assigned here. See the Sampling Tools Reference.

Stage Operations

Extraction, coding + weighting, refinement, and export are all invoked with a bundle_id on the Dataset Tools — there is no separate "run this Bundle" tool. A typical flow:

  1. create_bundle → get bundle_id
  2. create_bronze_dataset(bundle_id) → extract Bronze
  3. code_open_ends(bundle_id) (or its alias derive_silver) → codes open-ends, then weights, producing Silver
  4. create_gold_dataset(bundle_id) → refine Silver into Gold
  5. export_dataset(dataset_id, format) → export any ready stage
  6. get_bundle_quality(bundle_id) → the four-measure quality story at any point