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 detailed dataset information including column schema and metrics.

Parameter	Type	Required	Default	Description
dataset_id	string	Yes	—	Dataset UUID

Returns: Full dataset object with id, name, description, stage, source_type, row_count, column_count, column_schema, has_weights, weight_column, weighting_method, weighting_config, quality_score, processing_status, strategy_id.

---

create_bronze_dataset

Extract a Bundle's Bronze dataset. The Bundle already carries the questionnaire, campaign subset, and ad-hoc toggle — there is no free-form questionnaire/campaign selection at this tool. 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 extraction report.

---

code_open_ends (alias: derive_silver)

Derive a Bundle's Silver: code open-ended text into indicator categories, 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.

When the questionnaire has no open-ended (Textarea) columns, coding is skipped automatically and weighting runs directly on the Bronze data. 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.

Coding before weighting

Askalot codes open-ended answers into categories first, then weights once over the finished coded case base — this deliberately differs from a "weight first" workflow. Discovered categories become available as weighting variables 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", or "parquet"

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)

---

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"}
No completed surveys	{"error": "no_completed_surveys", "detail": "..."} — widen the campaign selection, enable ad-hoc surveys, or wait for more completions