Dataset Tools — MCP Tool Reference

Dataset tools implement the Bundle-scoped medallion data pipeline: a Bundle binds a Project, Questionnaire, and Campaign subset to one linear Bronze → Silver → Gold chain (see Bundle Tools for lifecycle operations). These tools extract survey responses into a Bundle's Bronze, derive its Silver (open-end coding, then post-stratification weighting on the coded case base), refine into Gold, and export in multiple formats. Quality is a Bundle concern, not a dataset one — see the quality tools in the Bundle Tools Reference.

Every dataset tool is Bundle-scoped

create_bronze_dataset and create_gold_dataset take a bundle_id, not a free-form questionnaire/campaign/source selection — the Bundle already carries that selection. Weighting a dataset other than a Bundle's own Bronze isn't offered by any tool.

list_datasets

List datasets with optional filters.

Parameter	Type	Required	Default	Description
stage	string	No	—	Filter by stage: "bronze", "silver", or "gold"
source_type	string	No	—	Filter: "campaign", "project", "upload", "weighted", or "refined"
campaign_id	string	No	—	Filter by campaign ID
limit	integer	No	100	Maximum results to return

Returns: { items: [...], count, limit }

---

get_dataset

Get a dataset's identity, lineage, metrics and status. This is the tool every pipeline step says to poll, so it is bounded — the response does not grow with the questionnaire.

Parameter	Type	Required	Default	Description
dataset_id	string	Yes	—	Dataset UUID

Returns: id, name, description, stage, source_type, source_dataset_ids, bundle_id, campaign_id, questionnaire_id, strategy_id, row_count, column_count, has_weights, weight_column, weighted_at, weighting_method, weighting_config, quality_score, processing_status, processing_error, data_path, created_at, invalid_cells.

processing_error is the reason a stage ended in error — the derive's own coding_produced_no_columns: refusal, for example. It is null on every other status. Read it whenever processing_status is error: without it a poll can see that a stage failed and not why.

The column schema is not here — read it with get_dataset_schema. It is the one unbounded field a dataset carries (89 KB of a 90 KB response on a 192-column Silver), so a poll spent tens of thousands of tokens re-reading an unchanging schema to see a 7-byte status string.

invalid_cells is {column: count} for the cells the extraction could not read as the type their column stores and therefore stored as blank — a Radio item holding prose, say. {} means the extraction checked and found none; null means the dataset predates the check. A blank written this way is otherwise indistinguishable from a respondent's skip, so read it before drawing conclusions about missingness.

---

get_dataset_schema

Get a dataset's column schema: per column its dtype, the item_id, item_title and control_type it came from, its labels map (code → caption), and its roster/indicator provenance.

Parameter	Type	Required	Default	Description
dataset_id	string	Yes	—	Dataset UUID
columns	string[]	No	—	Column names to return; omit for the whole schema

Returns: { dataset_id, stage, column_count, column_schema, returned, unknown_columns }.

column_count is the dataset's own, so with a columns filter it is larger than returned and the gap tells you how much of the schema you have not seen. A name you pass that the dataset does not have comes back in unknown_columns rather than being dropped, so a typo is distinguishable from a column the stage genuinely lacks.

Use columns on a real instrument. A 293-column schema is ~134 KB, larger than most agent tool-result budgets. Two moments need this tool at all: choosing Calibration Targets (which column, and what its labels map calls each code) and composing a Gold operations catalog (which columns exist to rename, remove or reorder). GET /api/v1/datasets/<id> is the other door and carries the whole schema — REST is the lane for large results.

---

create_bronze_dataset

Extract a Bundle's Bronze dataset. The Bundle already carries the questionnaire and its campaign subset — there is no free-form questionnaire/campaign selection at this tool. Previews are refused unconditionally, so no argument can fold a design-time test walk into the base. Re-running attaches the fresh Bronze to the Bundle chain and cascade-invalidates a downstream Silver/Gold (they become stale, not deleted — their recipes survive for a one-click re-derive).

Parameter	Type	Required	Default	Description
bundle_id	string	Yes	—	The Bundle whose Bronze to (re)extract
include_demographics	boolean	No	true	Include respondent demographic columns

Returns: { dataset_id, bundle_id, stage: "bronze", ... } with the extraction report, including invalid_cells (see get_dataset, which is where to read it on any later turn).

---

code_open_ends (alias: derive_silver)

Derive a Bundle's Silver: code open-ended text into one labelled categorical column per selected dimension, then rake (post-stratification weighting) over the coded case base. This is the only tool that produces a Silver dataset, and it always sources the Bundle's own ready Bronze — weighting any other dataset is not offered by any tool.

Parameter	Type	Required	Default	Description
bundle_id	string	Yes	—	The Bundle whose Bronze to derive into Silver

Returns: { silver_dataset_id, status: "processing", job_id } — the derive runs in the background. Poll get_dataset(dataset_id=silver_dataset_id) until processing_status is ready or error.

Coding runs over the units the Bundle's coding selection names — set it with set_coding_selection (see Bundle tools) — and, within each, over the dimensions a researcher selected in Balansor. When nothing is selected, coding is skipped and weighting runs directly on the Bronze data; that is an ordinary outcome, not an error. A selected unit whose dimensions nobody has reviewed produces no coded column and the derive still succeeds — check awaiting_review on get_bundle_coding before treating the result as complete. A derive is refused when a Calibration Target names a coded column whose dimension (weighting_factor_dimension_deselected) or whose whole unit (weighting_factor_deselected) the Bundle no longer selects — re-select it or drop the factor. derive_silver is registered as a second tool name for the same operation — agent prose that says "derive silver" and prose that says "code open ends" both resolve to it.

A derive that codes nothing ends error, not ready. One unit that cannot be coded is left uncoded and the rest still code, but if every unit the derive attempted produced no column, the Silver reaches processing_status: "error" with processing_error reading coding_produced_no_columns: followed by each unit key and why it yielded nothing. Treat it as terminal — a re-run meets the same units and produces the same nothing, so fix the cause (re-extract a Bronze whose text columns are missing, or repair the codebook in Balansor) before deriving again. This is distinct from an unreachable embedding backend, which the job retries on its own before any error is written.

Coding before weighting

Askalot codes open-ended answers into labelled categorical columns first, then weights once over the finished coded case base — this deliberately differs from a "weight first" workflow. A coded dimension becomes available as a weighting variable in the same derive.

---

create_gold_dataset

Refine a Bundle's ready Silver into its Gold, optionally transforming columns. Always sources the Bundle's own Silver; replaces any prior Gold in the chain.

Parameter	Type	Required	Default	Description
bundle_id	string	Yes	—	The Bundle whose Silver to refine
name	string	No	—	Name for Gold dataset. Defaults to "{bundle_name} — Gold"
fields	object[]	No	—	Column transformations

Each fields entry:

Field	Type	Description
id	string	Original column name
name	string	New display name
deleted	boolean	true to exclude column

Returns: { gold_dataset_id, name, stage: "gold", bundle_id, row_count, column_count }

Stage validation: The Bundle's Silver must be ready; a missing or non-ready Silver returns an error rather than falling back to Bronze.

---

export_dataset

Export a dataset in the specified format.

Parameter	Type	Required	Default	Description
dataset_id	string	Yes	—	Dataset UUID
format	string	No	"csv"	Export format: "csv", "xlsx", "spss", "parquet", or "rds"

Returns: { dataset_id, format, download_url, rows, columns, file_size_bytes }. The exported file is never returned inline — download_url is a short-lived link (expires a few minutes after minting) that lets you fetch the file directly over HTTPS with no further authentication; it can be reused any number of times until it expires. Request a fresh export if the link has expired.

Export Formats

Format	Extension	Description
csv	.csv	Universal format for most tools
xlsx	.xlsx	Excel with summary and schema sheets
spss	.sav	SPSS with variable and value labels
parquet	.parquet	Columnar format with full metadata (Snappy compression)
rds	.rds	R — categoricals arrive as factors, value labels as factor levels

---

delete_dataset

Delete a dataset and optionally its data file.

Parameter	Type	Required	Default	Description
dataset_id	string	Yes	—	Dataset UUID
delete_file	boolean	No	false	Also delete the Parquet data file

Returns: { deleted: true, dataset_id, dataset_info: { name, stage, row_count, data_path }, file_deleted }

---

Error Handling

Stage Validation

The Bundle pipeline enforces stage progression and readiness — a stage can't be skipped or exported while stale:

Operation	Requirement	Error
code_open_ends / derive_silver	Bundle's Bronze must be ready	{"error": "bronze_not_ready", "detail": "Extract a ready Bronze first"}
create_gold_dataset	Bundle's Silver must be ready	{"error": "silver_not_ready", "detail": "Derive a ready Silver first"}
export_dataset	Dataset must be ready (not processing/invalidated/error)	{"error": "conflict", "detail": "Dataset is '{status}', not ready — re-derive before export."}

Common Errors

Scenario	Response
Dataset not found	{"error": "Dataset {id} not found"}
Bundle not found	{"error": "not_found", "detail": "Bundle {id} not found"}
Strategy not found	{"error": "Sampling strategy {id} not found"}
No data file	{"error": "Dataset {id} has no data file"}
Invalid export format	{"error": "Invalid format. Allowed: csv, xlsx, spss, parquet, rds"}
No completed surveys	{"error": "no_completed_surveys", "detail": "..."} — widen the campaign selection or wait for more completions
Bundle selects no campaign	{"error": "no_campaigns_selected", "detail": "..."} — a Bundle's measurement base is the surveys of the campaigns it selects; assign at least one
Extraction could not write the dataset	{"error": "extraction_failed", "column": "q_x", "detail": "..."} — one column holds values that cannot be unified into a single type. The offending value is deliberately omitted (it is a respondent's answer); inspect that column's raw values, correct the source responses, and re-extract