Cube

List the Cube semantic model SOURCE files (the raw `.yml` / `.js` / `.py` schema files that define cubes and views) on a branch. Use this to discover which files to read/edit — it complements searchDataModel, which returns the compiled meta rather than the editable source. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. To publish, commit the dev branch from the Cube UI.

listDataModelFiles

Returns all Cube deployments and their agents that you can access. Use this to discover valid deploymentId values before passing them to any other tool: every tool takes an optional deploymentId and defaults to the deployment this session connected to, so pass one explicitly whenever the user asks about a different deployment. Passing an id not listed here is rejected. Every deployment supports the Auto agent (pass agentId: null to chat) — the default agent used when no specific agent is selected — in addition to any configured agents listed.

listDeployments

Fetch additional rows of a SQL query that a prior `chat` tool call already executed. The original query is re-run against the Cube semantic layer (the same SQL, no LIMIT/OFFSET injected) so it can be served from Cube's cache, and 100 rows starting at `offset` are returned. Use this ONLY when the user explicitly asks for more rows of a previous query. Identify the query via the `id` (uuid) of one of the SQL queries the prior chat response reported: take it from that response's `cubeSqlApiQueries[*].id`, which lists every query that turn ran. (`toolCalls[*].calls[*].id` carries the same uuid, but only for queries the answer cited explicitly, so it is often empty — prefer the former.) Page size is fixed at 100 — paginate by incrementing `offset` in steps of 100 (calls with different offsets may be issued in parallel) until the response reports `hasMore: false`. Do NOT call this tool to retry a failed query — re-issue the `chat` request instead.

loadQueryResults

Publish the workbook’s current dashboard draft to make it live. Idempotent — publishing an unchanged draft is a no-op (reported via `warning`). Returns the live dashboard `url` (share this with the user) and its `dashboardPublicId`. Only publish after updateDashboard returned success and you have verified the layout. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard → publishDashboard; readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

publishDashboard

Read the raw source of one Cube semantic model file (the editable YAML/JS defining a cube or view). Read this before writeDataModelFile so you edit on top of the current content rather than overwriting it. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. To publish, commit the dev branch from the Cube UI.

readDataModelFile

Read one saved report by its numeric id: its `title`, `sqlQuery`, chart category + spec (in `meta`), placement (`workbookId` — null for a standalone exploration — and `folderId`), `publicId`, and a shareable `url`. Use it to inspect a report before updateReport, or to see what a dashboard CHART widget (config.reportId) points at. Reads a single report by id — works for both standalone and workbook-bound reports, unlike a report list which the server filters to workbook-less rows. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard → publishDashboard; readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

readReport

Read a workbook: its name and its current dashboard `dashboardDraft` and `dashboardPublished` configs. ALWAYS call this before updateDashboard so you can pass the current draft as `oldDashboardConfig` (concurrency guard) and edit on top of it rather than overwriting. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard → publishDashboard; readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

readWorkbook

Run a Cube SQL query against the Cube SQL API (PostgreSQL dialect — see https://docs.cube.dev/reference/core-data-apis/sql-api) and return the result rows. Returns `schema` (columns), a page of `data` rows (page size 100), and `hasMore`/`totalRows` for pagination via `offset`. Read-only — it does not modify the model, workbooks, or reports. Use searchDataModel first to find the exact cubes/views and members to query — never guess member names. ## CubeSQL Query Rules Always follow data_model_rules when generating CubeSQL queries: <data_model_rules> - When querying measures, always use MEASURE() function, e.g. MEASURE(revenue), do not nest MEASURE() in other functions. SUM(MEASURE(revenue)) IS INVALID and NOT ALLOWED, use MEASURE(revenue) instead. - For filtered measures (applying a condition to a measure), use AGG(CASE WHEN condition THEN view_measure END) where AGG matches the measure's aggregation type: COUNT, SUM, AVG, MIN, MAX, COUNT DISTINCT, APPROX_DISTINCT. Use the bare view measure reference inside CASE, not MEASURE(). Example: SUM(CASE WHEN status = 'completed' THEN revenue END) AS completed_revenue. Never use filtered measures with number-type measures. - Do not quote identifiers - When using DATE_TRUNC, you can't use different time grains in SELECT statement and window functions. Convention to call it <date_dimension_name>_<date_trunc_part>, e.g. date_dimension_month. - Avoid using ROUND function - Never use joins between cubes and views. Use selects from views that contain all necessary members instead. You can use joins between CTEs though. - You can't GROUP BY with aliases. You need to use indexes: ```sql SELECT DATE_TRUNC('month', date_dimension) AS date_dimension_month, category_dimension, MEASURE(metric_column) FROM semantic_view WHERE semantic_view.category_dimension = 'value' GROUP BY 1,2 ORDER BY 1,2 LIMIT 5000 ``` - Avoid using aliases, except for time dimensions and custom dimensions and measures: ```sql SELECT DATE_TRUNC('month', orders_view.date) AS date_month, MEASURE(orders_view.count), MEASURE(orders_view.revenue), MEASURE(orders_view.revenue) / NULLIF(MEASURE(orders_view.count), 0) AS avg_order_value FROM orders_view GROUP BY 1 ORDER BY 1 LIMIT 5000 ``` - Your semantic model is Cube. Cube allows to model complex metrics and dimensions. - Views in Cube are user facing. Cube SQL is Postgres SQL. - NEVER query raw cubes directly. You should only query views. If a user asks to query a cube that has no corresponding view, suggest building a view for it first and ask for confirmation before proceeding. Measures must be queried with MEASURE() function, e.g. MEASURE(revenue). - For example if there's revenue measure then to query revenue you should use 'SELECT MEASURE(revenue) FROM sales' or 'SELECT DATE_TRUNC('month', order_date), MEASURE(revenue) FROM sales GROUP BY 1'. - Dimensions can be queried as regular columns. You always need to GROUP BY by dimensions. When selecting only dimensions (no measures), always use SELECT DISTINCT to avoid duplicate rows. For example: 'SELECT DISTINCT category, region FROM sales_view LIMIT 5000'. - Never guess names of measures and dimensions. Read Cube data model before making queries. - When making queries, you need to always set LIMIT (use 5000 as default). - Avoid using CTEs unless absolutely necessary. - You can't join views in Cube. When you need data from different views, you can use CTEs. - When generating SQL query, you must keep it simple, no subqueries, no joins, no complex expressions. - For custom sorting, create a CASE dimension in SELECT (e.g. CASE WHEN ... THEN 1 ... END AS sort_order) and ORDER BY that column. Do not put CASE expressions directly in ORDER BY. - For string filtering, default to ILIKE for case-insensitive matching unless the user explicitly requests case-sensitive LIKE. For example: WHERE client_name ILIKE '%acme%' for default matching, or WHERE client_name LIKE '%Acme%' when case-sensitive matching is explicitly requested. Use NOT ILIKE by default for negated patterns unless NOT LIKE was explicitly requested. </data_model_rules>

runQuery

Search the Cube semantic model by similarity — views and their measures & dimensions — to discover what is queryable. Returns compact records (name, title, description, type) you can then reference in a runQuery SQL statement. Call this before runQuery to find the exact view and member names.

searchDataModel

Enter development mode and start a dev worker. Returns the `branchName` you MUST pass to writeDataModelFile / deleteDataModelFile / getDataModelChanges. Editing always happens on this dev branch — the deploy branch is never writable. Call this first, before any edit. To RESUME a specific edit later, pass the same feature-branch name you used before; omitting `branchName` starts a NEW edit session each call, so reuse the returned branchName for all follow-up tools rather than calling this again. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. To publish, commit the dev branch from the Cube UI.

startDataModelEdit

Save the dashboard layout (the full `widgets` array) to the workbook DRAFT. This does not go live until publishDashboard. Send the COMPLETE widget set every time — this replaces the draft widgets (other top-level draft fields are preserved). CHART widgets must reference a real reportId from a createReport call made WITH this same workbookId; an id from another workbook or from a standalone (workbook-less) report is rejected and nothing is saved. Grid rules: 12 columns (x + w ≤ 12); CHART h≈11 (KPI-style ~w=3, h=3 with { hideTitle:true } and no title), TEXT h is recomputed from its markdown server-side (pick any reasonable h; just size w), FILTER/TIME_GRAIN h=2 (w=3) on the top control row (y=0), DIVIDER h=1 and SPACER h=2 (both full-width w=12). Pass `oldDashboardConfig` (from readWorkbook) for a safe concurrent update. Returns a `url` to the updated dashboard you can share with the user. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard → publishDashboard; readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

updateDashboard

Edit an EXISTING report in place, KEEPING its reportId. Do NOT recreate a report to change it; that orphans the CHART widgets pointing at it. Send only the fields you want to change; omitted fields are left untouched. You can change: `title`; `sqlQuery`; the visualization (`chartCategory` + its matching spec — table/vega/kpi/html/map); and placement — set `workbookId` to a workbook id to bind it there, or `null` to detach it into a standalone exploration, and `folderId` to file a standalone report. Editing title/SQL/visualization keeps every referencing widget rendering. CHANGING `workbookId` DOES NOT: a dashboard CHART widget resolves its report from its OWN workbook's report list, so moving a report out of (or between) workbooks empties every tile on the old workbook's dashboard that referenced it — the same "deleted" empty state deleteReport warns about. Before changing `workbookId` on a report a dashboard uses, call readWorkbook and re-point or remove those widgets with updateDashboard first. Works for both standalone and workbook-bound reports. Returns the reportId and a `url`. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard → publishDashboard; readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

updateReport

Create or overwrite a Cube semantic model source file on your dev branch (whole-file replacement — send the COMPLETE content). After saving, the dev worker recompiles the model and this returns `valid` plus any `validationError`. If it does not compile, fix the content and call this again — the file stays saved so you can iterate. Requires the dev branchName from startDataModelEdit. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. To publish, commit the dev branch from the Cube UI.

writeDataModelFile