datasets

name	datasets
description	Datasets tools for Dataspheres AI

Datasets

Tool reference for this resource group, mirrored by hand from the platform live /api/mcp/schema schema.

Tools

add_dataset_rows — Add Dataset Rows

Creates directly add rows to a dataset (bypasses preview). only use when the user explicitly typed the rows themselves. never use after research or ai generation — use generate_dataset_rows instead, which gives a review step.. Requires MODERATOR+ role in the datasphere. Required fields: datasphereId (string); datasetId (string); rows (array). Show a preview of the operation and get explicit confirmation from the user before executing.

Field	Type	Required	Description
datasphereId	string	yes	Datasphere ID
datasetId	string	yes	Dataset ID
rows	array	yes	Array of row objects matching the dataset schema

create_dataset — Create Dataset

Creates create a structured data table with columns and rows in a datasphere.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ step 0 — plan the charts first (do this before designing columns) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

before calling this tool, mentally plan the 3-5 data cards you intend to build from this dataset. the schema must support those charts. this is the single most important thing you can do for the user.

ask yourself:

1. what's the headline kpi? (sum, average, or count → requires a numeric or currency column, maybe grouped)
2. what's the ranking chart? (top n by metric → requires a category column + a numeric)
3. what's the composition chart? (share of total → requires a low-cardinality category + a numeric)
4. what's the trend chart? (metric over time → requires a date column + a numeric and at least 8-12 distinct time points to show a real trend)
5. what's the breakdown chart? (one category split by another → requires two low-cardinality categories + a numeric)

your schema must support all of those questions. if your schema can only answer 2 of the 5, redesign it before calling create_dataset.

━━━ column types — use the right one (critical) ━━━ these are the only valid type strings — any other value will be rejected by the validator:

text, longtext, number, currency, rating, scale, date, datetime, time, boolean, select, multiselect, url, email, phone, image, file, audio, video

⚠️ there is no "category" type — use "select" for enums (with an options[] array). ⚠️ there is no "percentage" type — use "number" for 0-100 values (or "scale" for bounded). ⚠️ there is no "enum" type — use "select".

type precision matters because the renderer formats values by type and chart viability checks gate on type:

• "currency" — money amounts (usd, eur, etc). renders as "$1.2b" / "$5m" / "$850k". mandatory for columns named with any of: cost, price, budget, total, spend, expense, amount, fee, payment, revenue, profit, loss, funding, commitment, usd, money, monetary, compensation, reparation, settlement, grant, donation, pledge. do not use "number" for these — use "currency".
• "number" — plain counts, quantities, scores without units. renders as "1.2m" / "42". use this for any 0-100 percentage-like value too (there is no "percentage" type).
• "rating" — bounded 1-5 / 1-10 stars. renders as "7 ★".
• "scale" — bounded numeric scale (e.g. nps 0-10, likert 1-7). similar to rating but renders as a bar.
• "date" — iso 8601 dates (yyyy-mm-dd). enables time-series charts.
• "datetime" — iso with time. same as date but finer resolution.
• "time" — time-only value.
• "select" — enum with a fixed set of values, single choice per row. must include an "options" array in the column definition listing the allowed values. enables donut/pie/sankey charts and guarantees low cardinality. this is the type formerly called "category" in the old docs.
• "multiselect" — enum, multiple choices per row. also requires "options" array. cell values are arrays of strings.
• "boolean" — true/false.
• "text" — freeform short string (name, title, short phrase). limit to ≤8 words. never paragraphs.
• "longtext" — multi-sentence prose. use sparingly — longtext columns can't be grouped or charted.
• "url" — hyperlinks for source attribution.
• "email" — email addresses.
• "phone" — phone numbers.
• "image" / "file" / "audio" / "video" — media attachments.

for select columns, the schema must look like: { "name": "status", "type": "select", "options": ["active", "contested", "concluded", "aspirational", "early stage"] } not: { "name": "status", "type": "category", "options": [...] } ← "category" is not valid { "name": "status", "type": "text" } ← loses enum guarantees { "name": "status", "type": "select" } ← missing required options[]

━━━ quantitative bias ━━━ every dataset you design should unlock the full range of chart types — bar, line, pie, scatter, sankey, kpi, funnel, gauge.

minimum schema shape (aim for this on every new dataset):

• at least 1 date column (iso 8601 format, type: "date") — enables trend lines, time series, stacked areas
• at least 2 numeric columns (type: "number") — enables kpis, scatter, bubble, gauges, ranked bars
• at least 2 categorical columns (type: "text" but with low cardinality ≤ ~15 distinct values) — enables donuts, pies, rankings, sankey
• optional: 1-2 entity/name columns for labels (text, higher cardinality ok)
• optional: 1 url column for source attribution

━━━ one concept per column ━━━ every column must hold a single, indexable concept. if you're tempted to have a column like "alignment" whose values will be "strong — asserts x; rejects y", that's two concepts in one cell and it will break every chart. split it into "alignmentlevel" (enum weak/moderate/strong) + "alignmentreason" (short phrase) instead.

prefer 15 short columns over 8 columns stuffed with paragraphs. specifically:

• enum/status/stage/tier columns → hold 1–4 word values only. design the schema so these are picked from a fixed set.
• counter/total/score columns → numeric, single value, no units baked in.
• reasoning/rationale/notes → a separate short-text column, ≤20 words.
• never embed semicolons, em-dashes, or compound "x — y" constructions in categorical column values.
• when in doubt: ask "can i sort, group, or filter by this value?" if not, it's too rich for a cell — split it.

good schema example (for a "worldbuilding community timeline" dataset): [ { "name": "date", "type": "date" }, { "name": "event", "type": "text" }, { "name": "category", "type": "select", "options": ["community", "platform", "media", "tools"] }, { "name": "region", "type": "select", "options": ["na", "eu", "apac", "global"] }, { "name": "status", "type": "select", "options": ["active", "archived", "draft"] }, { "name": "participants", "type": "number" }, { "name": "impact score", "type": "rating" }, { "name": "engagement hours", "type": "number" }, { "name": "source url", "type": "url" } ]

good schema example (for a "reparations frameworks" dataset — this is the shape for rich legal/case research): [ { "name": "framework name", "type": "text" }, { "name": "region", "type": "select", "options": ["caribbean", "europe", "sub-saharan africa", "north america", "pacific", "arctic", "pan-african"] }, { "name": "legal basis short", "type": "text" }, // ≤5 words { "name": "alignment level", "type": "select", "options": ["weak", "moderate", "strong", "emerging"] }, { "name": "framework stage", "type": "select", "options": ["truth-telling", "acknowledgment", "structural repair", "community-centered"] }, { "name": "status", "type": "select", "options": ["active", "concluded", "contested", "aspirational", "early stage", "completed"] }, { "name": "year established", "type": "date" }, { "name": "monetary commitment", "type": "currency" }, // not "number" — must be "currency" because it's money { "name": "structural repair", "type": "boolean" }, { "name": "policy instrument", "type": "select", "options": ["multilateral treaty", "bilateral treaty", "federal legislation", "state legislation", "municipal resolution", "executive agreement", "civil litigation", "political declaration"] }, { "name": "outcome score", "type": "rating" }, { "name": "source url", "type": "url" } ] note how every narrative concept from the bloated version is now an enum column with a fixed set of options. the old "gaines alignment" blob with a long em-dash reason is now just "alignment level" = "strong". the reason belongs on the source url, not in a spreadsheet cell.

anti-pattern (do not do this): a dataset with only text columns (title, description, notes) supports almost no chart types — only count by grouping. if the user asks for a dataset that sounds text-heavy, add quantitative columns anyway (impact score, count of something, duration, rating, etc.) so the dataset can power real insights.

human-in-the-loop: if you're unsure what quantitative metrics make sense for the user's topic, propose 2-3 candidate schemas and ask which one fits their needs. don't guess silently.

auto-chain: after a dataset is created, offer to fill it: "want me to generate ~20 rows of realistic data to get started? you'll review before anything saves." → generate_dataset_rows. after rows are saved, offer to build charts: "now that the data is in, want me to build a few data cards from it?" → create_data_card. never chain silently — always ask.. Requires MODERATOR+ role in the datasphere. Required fields: datasphereId (string); name (string) — max 200 chars; schema (array). Optional: description. Show a preview of the operation and get explicit confirmation from the user before executing.

Field	Type	Required	Description
datasphereId	string	yes	Datasphere ID
name	string	yes	Dataset name
description	string	no	What this dataset tracks
schema	array	yes	REQUIRED: Array of column definition objects. VALID TYPES (only these): text, longtext, number, currency, rating, scale, date, datetime, time, boolean, select, multiselect, url, email, phone, image, file, audio, video. There is NO "category" type — use "select" with an options[] array. There is NO "percentage" type — use "number". Every money column MUST be "currency" not "number". Example: [{"name":"Date","type":"date"},{"name":"Region","type":"select","options":["NA","EU","APAC"]},{"name":"Participants","type":"number"},{"name":"Budget","type":"currency"},{"name":"Score","type":"rating"}].

delete_dataset — Delete Dataset

Deletes delete a dataset and all its data. Requires ADMIN+ role in the datasphere. Required fields: datasphereId (string); datasetId (string). Show a preview of the operation and get explicit confirmation from the user before executing.

Field	Type	Required	Description
datasphereId	string	yes	Datasphere ID
datasetId	string	yes	Dataset ID

generate_dataset_rows — AI Fill Dataset

Creates ai-generate preview rows for a dataset. rows are not saved automatically — the user must review and approve them first.

bias toward realistic quantitative data. the dataset's chart-building power depends entirely on whether the numeric columns actually vary + the categorical columns have meaningful low-cardinality distributions.

━━━ hard rule: one concept per column ━━━ each cell value must be a single, indexable value. never cram multiple concepts, clauses, or subjective narrative into one cell — that breaks every chart type and makes the data impossible to filter, group, or aggregate.

cell length budgets (respect strictly):

• categorical / label columns (category, region, status, type, stage, framework, etc.): 1–4 words max. short noun phrases. examples: "active", "community growth", "north america", "stage 3 repair". anti-example (do not do): "strong — asserts inalienable right to repair rooted in historical dispossession; rejects statute of limitations as inapplicable to ongoing harm" ← this has 5 concepts welded together. do instead: put that in a description column or split into 3 columns: alignment="strong", alignmentreason="asserts inalienable right to repair", statuteoflimitationsstance="rejected".
• name / title columns: 1–8 words. "caricom reparations commission", "luxembourg agreement", "evanston reparations program".
• description / summary columns (when the schema explicitly includes one): 1 sentence, ≤25 words. never more than one sentence — put longer prose in an embedded page, not a dataset cell.
• notes / narrative columns: ≤60 words, still one paragraph. only include if the user explicitly asks for freeform narrative per row.
• numeric columns: a single number, no units inside the cell (units belong in the column name or a separate unit column).
• date columns: a single iso date string.
• url columns: one url.
• no em-dash prose inside categorical fields (— should never appear in a category / status / stage / alignment cell).

━━━ when the user's topic needs narrative depth ━━━ if the subject matter is inherently rich (case law, research findings, historical events), the right move is to split concepts across more columns rather than making any one cell longer. concretely:

• instead of "gaines alignment" = "strong — asserts inalienable right…; rejects statute of limitations…", use:
  • alignmentlevel (enum: weak | moderate | strong | emerging): "strong"
  • alignmentdoctrine (short phrase): "inalienable right to repair"
  • statuteoflimitationsstance (enum: rejected | waived | contested | not applicable): "rejected"
• instead of "structural repair included" = "yes — 10-point plan includes education, health, cultural institutions, and psychological rehabilitation", use:
  • structuralrepair (bool): true
  • repairmechanisms (short comma list, ≤6 items, each ≤3 words): "education, health, culture, psychology"
• instead of "current status" = "active — negotiations ongoing with former colonial powers", use:
  • status (enum: active | concluded | contested | aspirational | early stage): "active"
  • statusdetail (short ≤10 words): "negotiations with former colonial powers"

a dataset with 15 short columns beats a dataset with 8 columns stuffed with paragraphs every time for charting.

━━━ strict type-respect rules (the cell value must match the column type) ━━━

every row value must match its column's declared type exactly. the renderer formats based on type; a value in the wrong shape breaks downstream charts.

• currency (money — usd, eur, etc): value = raw whole number. no "$", no commas, no suffix, no "usd". ✅ 89000000000 ❌ "$89b" "$89,000,000,000" "89b" "89 billion usd" null (use 0 instead for unknown)

• number (plain count / quantity / score): value = raw number. integer unless the column is a rate/ratio. ✅ 1500 42.5 ❌ "1,500" "1.5k" "1500 people"

• percentage (0-100 proportion): value = raw number 0-100. no "%". ✅ 42 87.5 ❌ "42%" 0.42 "87.5 percent"

• rating (1-5 or 1-10 bounded): value = integer in the declared range. ✅ 7 ❌ "7/10" "7 stars" "seven"

• date (yyyy-mm-dd): value = iso date string. ✅ "2021-05-19" ❌ "may 19, 2021" "05/19/2021" 2021 "q2 2021"

• datetime (iso with time): value = iso datetime string. ✅ "2021-05-19t14:30:00z" ❌ "may 19, 2021 2:30pm"

• select / multiselect (enum — must be one of the declared options; "multiselect" values are arrays of options): value = one of the exact strings in the column's options[] array. case-sensitive. ✅ "active" (when options = ["active","archived","draft"]) ❌ "active" "active — ongoing" "active; some constraints" "live" (not in options) if you don't know which option fits, pick the closest one. don't invent new ones.

• boolean (true/false): value = literal true or false. no strings. ✅ true false ❌ "yes" "yes — partially" "y" 1

• text (short entity name / 1-sentence description): value = plain string. if the column name implies a description, limit to one sentence ≤25 words. no narrative paragraphs. ✅ "caricom reparations commission" ❌ "caricom reparations commission — a multilateral body formed in 2013 to negotiate..." (this is a paragraph, not a cell value)

• url: a single url string. no trailing spaces, no "http://..." vs bare domain mixing.

━━━ common anti-patterns to avoid ━━━

1. stuffing multiple concepts into one cell: ❌ { alignment: "strong — asserts inalienable right to repair; rejects statute of limitations" } ✅ { alignmentlevel: "strong", alignmentdoctrine: "inalienable right to repair", statuteoflimitationsstance: "rejected" }

2. using "text" for what should be "select": ❌ { status: "active", status: "active", status: "active ongoing", status: "in progress" } (inconsistent variants) ✅ declare status as type:"select" with options:["active","concluded","contested",...], then every row uses an exact option.

3. using "number" for money: ❌ { cost: 1500000 } when the column is clearly money ✅ column is type:"currency", value is 1500000. renderer shows "$1.5m".

4. em-dashes and semicolons in category cells: ❌ { region: "north america — urban" } ✅ { region: "north america", subtype: "urban" }

5. row count that can't support intended charts: ❌ generating only 5 rows for a trend_line use case (needs ≥5 distinct dates). ✅ generate at least 15-20 rows with varied dates if the user wants time-series charts.

━━━ numeric range guidance ━━━

• for numeric columns: realistic values across a sensible range (not all zeros, not constant placeholders). vary them so bar charts, trend lines, and scatter plots show real shape. round-ish numbers that look human (not random 4-decimal floats unless the column is a rate/ratio).
• for date columns: spread values across a reasonable time span so time-series visuals reveal trends. don't cluster everything in one month unless the topic requires it.
• for categorical columns: pick 3-8 distinct values per low-cardinality column and reuse them consistently across rows (so donut/pie/rankings charts have proper slices). don't make every row's category unique.

example prompt (for a "community timeline" dataset): "generate 20 rows of community events from 2019-2024. spread dates across the range. pick from 6 categories: founding, platform, growth, media, tools, event — reuse them so each has 2-4 rows. pick from 4 regions: na, eu, apac, global. participants should range 50-1500 (skew higher for platform events). impact score 1-10. engagement hours 5-80. event name ≤6 words. description ≤20 words, one sentence."

example prompt (for a reparations-framework dataset): "generate 15 frameworks. each row: frameworkname (≤6 words), region (enum of 6), legalbasisshort (≤5 words, e.g. 'luxembourg agreement 1952'), alignmentlevel (enum: weak|moderate|strong|emerging), stage (enum: truth-telling|acknowledgment|structural repair|community-centered), status (enum: active|concluded|contested|aspirational|early stage), yearestablished (date), monetarycommitmentusd (number), structuralrepair (bool), policyinstrument (≤4 words, e.g. 'state legislation'), outcomescore (1-10), sourceurl. keep every cell ≤5 words except numeric/date/url. no narrative in categorical fields."

ari agent instructions (how to talk about this):

• never say "rows are in" or "data has been added" — the rows are a preview only
• say: "i've generated n rows for preview. click 'review & save rows' to open the dataset, review the data, and save what looks good."
• the user sees an amber-colored card with a "review & save rows" button
• rows only persist after the user reviews them in the fullscreen dataset editor and clicks save
• if the user asks to "fill the dataset", clarify: "i'll generate preview rows — you'll get to review and edit them before anything is saved."

auto-chain: after rows are generated, offer to build 2-3 data cards from the dataset immediately so the user sees the quantitative payoff. "now that your dataset has data, want me to build a few charts from it?"

field rules: use exact lowercase field names: "datasphereid", "datasetid", "count", "prompt".. Requires MODERATOR+ role in the datasphere. This operation costs tokens — always confirm with the user before executing. Required fields: datasphereId (string); datasetId (string). Optional: count [default: 10], prompt. Show a preview of the operation and get explicit confirmation from the user before executing.

Field	Type	Required	Description
datasphereId	string	yes	Datasphere ID
datasetId	string	yes	Dataset ID
count	number	no	Number of rows to generate (default: 10)
prompt	string	no	Instructions for data generation

list_datasets — List Datasets

Retrieves list all datasets in a datasphere. Requires PARTICIPANT+ role in the datasphere. Required fields: datasphereId (string).

Field	Type	Required	Description
datasphereId	string	yes	Datasphere ID

update_dataset — Update Dataset

Updates update dataset name, description, or schema. Requires MODERATOR+ role in the datasphere. Required fields: datasphereId (string); datasetId (string). Optional: name, description. Show a preview of the operation and get explicit confirmation from the user before executing.

Field	Type	Required	Description
datasphereId	string	yes	Datasphere ID
datasetId	string	yes	Dataset ID
name	string	no	New name
description	string	no	New description