data-cards

name	data_cards
description	Data Cards tools for Dataspheres AI

Data Cards

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

Tools

create_data_card — New Data Card

Creates a live data card (chart) for a dataset. The server computes a shadow view of the dataset, picks real columns from it based on your prompt + the template's contract, runs the LLM to generate the query, validates it, and creates the card.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HIL FLOW (CRITICAL — same as every other create_* tool, NO shortcuts)

create_data_card MUST follow the standard collecting → confirming → executing flow. Do NOT skip the confirming step. Do NOT set phase='executing' on your first emit. Do NOT auto-fire it because "the server can build it in one round trip". The user always sees the preview card and clicks Approve FIRST, then the build runs.

Step-by-step:

1. Decide template + prompt + datasetId based on screen context.
2. Emit a tool_confirmation block with phase='confirming' showing template, prompt, dataset name. WAIT.
3. User clicks Approve in the UI → next turn from the user will trigger the executing phase server-side.
4. Server fires the build endpoint, returns the card, the dataset editor's card carousel refreshes via the data-card-created event.
5. In your reply: confirm in one short sentence, NO re-emit of the tool_confirmation block.

If you set phase='executing' before the user has explicitly approved, the server will REFUSE the bypass and force you back to 'confirming' — and the user will see your attempted shortcut as a regression. Don't do it. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

━━━ AVAILABLE TEMPLATES ━━━ TRENDS (need a date column):

• trend_line: single line, metric over time
• multi_trend: one line per category over time
• stacked_area: stacked area per category over time

RANKINGS (need a category column):

• top_rankings: horizontal bar, top 10
• category_comparison: vertical bar, all categories
• bottom_rankings: horizontal bar, bottom 10

COMPOSITION (need a low-cardinality category):

• donut_breakdown: donut with center KPI
• simple_pie: solid pie (2-8 slices)
• treemap_composition: nested rectangles

RELATIONSHIPS (need 2-3 numerics):

• correlation_scatter: raw-row scatter
• bubble_chart: scatter + size dimension

SNAPSHOTS (single number):

• kpi_metric: sum or count
• average_value: avg of a numeric
• progress_ring: gauge

FLOW (need 2 categories):

• sankey_flow: source → target flow
• funnel_chart: stage-by-stage drop-off

━━━ WHEN TO CALL ━━━

1. The user asks for a chart + a dataset exists → call this tool.
2. You're composing a page and need a specific visualization → call this tool, then embed the returned card id via the dataCard node in your create_page content.
3. No dataset exists yet → call create_dataset + generate_dataset_rows first, then loop back here.

━━━ CHECK THE DATA SHAPE BEFORE PICKING A TEMPLATE ━━━ The biggest failure mode is picking a chart whose data shape isn't supported by the dataset. Before calling create_data_card, look at the RealityEngine cache entities (or call list_data_cards + list_datasets) and reason about:

• How many rows does the dataset have?

  • <5 rows → prefer kpi_metric or category_comparison. Never pick trend_line or correlation_scatter (they need ≥5 data points).
  • 5-30 rows → most templates work.
  • 30+ rows → prefer treemap_composition over donut_breakdown (too many slices).

• How many distinct values does each column have?

  • date column with <5 distinct values → DO NOT pick trend_line / multi_trend / stacked_area (the chart is 2 dots, not a trend). Pick category_comparison by date instead.
  • category column with >12 distinct values → DO NOT pick donut_breakdown or simple_pie (confetti of slices). Pick treemap_composition or category_comparison.
  • category column with <3 distinct values → DO NOT pick top_rankings (pointless ranking). Pick kpi_metric or donut_breakdown.

• What's the numeric column count?

  • 0 numerics → kpi_metric uses COUNT(), top_rankings uses COUNT().
  • 1 numeric → kpi_metric, top_rankings, trend_line, donut_breakdown.
  • 2+ numerics → correlation_scatter is available. 3+ enables bubble_chart.

• Is there time AND quantity?

  • date + numeric → trend_line (the most powerful combo)
  • date + category + numeric → stacked_area or multi_trend

━━━ WIDE vs LONG FORMAT — CRITICAL FOR MULTI-LINE CHARTS ━━━ multi_trend and stacked_area require LONG-format data: one row per (date, category) pair — a "Stat Type" column holds the series name and a single "Value" column holds the number.

Most user datasets are WIDE-format: one row per entity/date, separate columns for each metric (e.g. "Season", "Points", "Assists", "Rebounds"). multi_trend CANNOT work on wide-format data.

You have NO tool to transform existing rows. update_dataset can add a schema column but CANNOT migrate data. Do NOT offer to "reshape", "pivot", or "restructure" existing rows — you cannot execute that operation.

When the user wants to compare multiple metrics from a wide-format dataset:

• Do this: build one trend_line card per metric (e.g. Points over Seasons, Assists over Seasons, Rebounds over Seasons) — each is a valid single-metric trend and takes one create_data_card call each.
• Never do this: offer to reshape/pivot the data into long format — you cannot run that transformation.

━━━ BUILD A VARIETY, NOT 3 BAR CHARTS ━━━ When the user asks for "a few charts" or "some data cards", vary the chart types. A strong starter set for a rich dataset:

1. kpi_metric (headline number — total / count / avg of the primary numeric)
2. top_rankings (best N by that same numeric)
3. donut_breakdown (composition by the primary category)
4. trend_line (if a date column has ≥8 distinct values)

Don't build 3 bar charts of the same data. Don't build a pie chart AND a donut of the same column. Each chart should answer a DIFFERENT question.

━━━ SERVER WILL REJECT BAD FITS ━━━ If you pick a template whose data shape isn't supported (e.g. trend_line on 3 dates), the server's viability pre-check will reject it with { ok: false, reason, missing, suggestedFix } BEFORE the LLM call. Trust those errors — they tell you exactly what's wrong and how to fix it (usually by picking a different template or adding more rows).

━━━ HUMAN-IN-THE-LOOP ━━━

• If the user's request maps to multiple reasonable templates (e.g. "show me growth" could be trend_line OR kpi_metric), present 2-3 options and ASK which viz feels right.
• If the datasphere has multiple datasets and the user hasn't said which, list them and ASK before proceeding.
• Always show the preview card before firing — requiresConfirmation: true handles this automatically.

━━━ ON FAILURE ━━━ The server may return { ok: false, reason, alternative: {...} } when the picked template can't be built from the current dataset. In that case the alternative is a CONCRETE working card (full query + template + name). Surface it to the user with "this didn't fit, but here's one that does" and ask if they want to accept it.

Response on success: { ok: true, card: { id, name, description, vizType, datasetId, datasphereId, query, queryResults, vizConfig } }

The returned card.id is immediately usable in a dataCard HTML node via:

[Data Card: {card.id}]

━━━ AUTO-CHAIN ━━━ After creating a data card, offer the next logical step:

• "Want me to write a page about this?" → create_page with the card embedded
• "Build more cards from the same dataset?" → loop create_data_card with a different template
• "Add this to a page you're working on?" → update_page (if there's an active page in conversation) HIL at every hop — ask before chaining. NEVER re-emit an already-approved create_data_card confirmation.

Field	Type	Required	Description
datasphereUri	string	yes	Datasphere URI slug
datasetId	string	no	Dataset id the card pulls from. Optional — if omitted, the server auto-picks the most recently updated dataset in the datasphere. Only omit when the user clearly means "the latest one".
templateId	string	yes	One of: trend_line, multi_trend, stacked_area, top_rankings, category_comparison, bottom_rankings, entity_leaderboard, donut_breakdown, simple_pie, treemap_composition, correlation_scatter, bubble_chart, kpi_metric, average_value, progress_ring, sankey_flow, funnel_chart. Use entity_leaderboard when the user wants to see individual entities (people, companies, products) ranked by a metric — NOT categories counted or summed.
prompt	string	yes	Plain-English description of what the card should show — e.g. "top categories by event count" or "participants over time by region". The server uses the shadow view + this prompt to generate the formula.

list_data_cards — Data Cards

Lists data cards (live charts) within the CURRENT datasphere. Always scoped — this endpoint physically cannot return cards from another datasphere because the server filters by dataset.datasphereId. Use this BEFORE create_page or update_page when the user wants a page that includes existing visualizations — you get the card ids you need to embed them via the dataCard node.

SCOPE RULES (CRITICAL):

• ALWAYS pass the current datasphereUri from the URL/screen context. Never the "default" datasphere, never a different one.
• When the user is on /app/{uri}/datasets/{datasetId}/edit, ALSO pass datasetId to narrow to just that dataset's cards. The screen already tells you which dataset — use it.
• This is NOT a cross-platform card browser. It only returns cards the user already has access to in that specific datasphere.

WHEN TO CALL:

• User says "write a page about X using our charts" → call this first (with current datasphereUri), pick the relevant cards by name/description, then embed them in the create_page content HTML.
• User says "create a page from this dataset" while on a dataset editor → call this with datasphereUri + datasetId to get ONLY that dataset's cards.
• User says "what data do we have on X?" → call this + list_datasets together to show them everything available.
• User says "use the bar chart of top categories" → call this to find the exact card id.

RESPONSE FIELDS (each card has):

• id, datasetId, datasphereId, datasphereUri — all 4 required when embedding
• name, description, vizType — for picking which cards fit the user's intent
• datasetName, datasetRowCount — for context

AFTER CALLING:

• If the user's intent is clear (e.g. "write a page about growth"), IMMEDIATELY proceed to create_page embedding the relevant card ids in the HTML via
  [Data Card: id]
  .
• If it's ambiguous, reply with a short summary of the cards and ask which ones to include.

Returns: { cards: [...], datasphereId, datasphereUri, total }

Field	Type	Required	Description
datasphereUri	string	yes	Datasphere URI slug (e.g. "carlos-rodriguez"). MUST be the CURRENT datasphere the user is working in — read it from the URL (/app/{uri}/...) or screen context, never from a different datasphere.
datasetId	string	no	Optional — narrow results to a single dataset. Pass this when the user is on /app/{uri}/datasets/{datasetId}/edit and asks ARI to do something with "this dataset's cards". Cross-datasphere filtering is still enforced server-side.