Skip to main content
Glama

NEM Explorer (ScadaMiner)

save_dashboard

Create or update a saved dashboard: a live page NEM Explorer hosts for this user at a stable URL, whose panels re-run their queries against current data every time it is opened. THIS is the tool for "build me a dashboard", "can I have a page that tracks X", "add a chart to my Y dashboard", or anything the user wants to come back to. Not share_artifact — that publishes a one-off write-up to a PUBLIC page; a dashboard is private, live, and editable. You author a JSON document, not code: named read-only SQL queries plus panels (markdown, chart, table, stat) that reference them by name. A dashboard whose panels plot time should declare a time block — it gives the page a time picker and drag-to-zoom — and filter and bucket with $__timeFilter(ts) and $__timeGroup(ts). When the user wants to switch region on the page, declare params and read them in SQL as {region:String} rather than saving a dashboard per region; a detail page per row is one dashboard with a parameter plus a table links entry, not a dashboard per row. Call get_dashboard_guide for the vocabulary and the rules. To EDIT an existing one, call get_dashboard first and pass its name here along with the complete edited spec — a save REPLACES the spec, it does not merge. Passing name plus a different title renames it (and changes its URL). Every query is executed before anything is stored: if one fails, or a panel plots a column its query does not return, NOTHING is saved and you get every problem back at once, with the real column names. Fix them all and call again. Returns the url to give the user. A heavy dashboard can take a while to save. If this call times out, the save may still have landed: call get_dashboard. If its revision moved, its last_save carries that save's warnings. If it did not move (or a new dashboard does not exist), the save was refused or is still running and no reason is stored: save again to see why, with a narrower widest date option if a long window is the likely cause.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "title": "<title>"
    },
    "name": "save_dashboard"
  }
}

Input Schema

NameRequiredDescriptionDefault
ctesNoSQL several queries repeat, declared once: `{"name": "owners", "sql": "SELECT …", "description": "…"}`. A query that names `owners` (`FROM owners`, `JOIN owners`) gets it prepended as a CTE. A shared CTE may name the ones declared before it.
nameNoThe dashboard to overwrite, as its name or its title. Omit to create a new one. Pass this whenever the user is editing something that already exists — "add a capacity factor chart to my SA wind dashboard". Without it a second dashboard is created alongside the first, which is rarely what anyone wants and is invisible until they open the list. Give both `name` and a different `title` to rename: the name follows the title, and the old one stops resolving.
timeNoThe dashboard's time range — a time picker on the page, drag-to-zoom on every time chart, and `from` / `to` / `bucket` in the queries: `{"default": "now-7d", "min_interval": "5m", "max_span": "1y"}` `default` (and optional `default_to`, `now` unless set) are time expressions: `now-7d`, `now-6h`, `now-1M/M` (start of last month; `m` is minutes, `M` months), `now/fy`, or `YYYY-MM-DD`. `min_interval` is the data's own resolution (`4s`, `5m`, `30m`, `1d`; default `5m`) and `max_span` the widest range a viewer may pick (default `1y`). `earliest` (`2026-10-01`) is where the data starts, for something that began on a known day: an earlier pick is cut to it. Queries use `$__timeFilter(ts)` and `$__timeGroup(ts)` (or `$__dateFilter(d)` / `$__dateGroup(d)` on a Date column), or the raw placeholders `{from:DateTime}`, `{to:DateTime}`, `{bucket:UInt32}`. A query too heavy for the whole `max_span` caps its own window with `$__timeFilterMaxSpan(ts, 35d)`, not an `AND dateDiff(...)` condition.
titleYesThe dashboard's headline, e.g. "SA wind vs price". Also what its name is derived from on first save: "SA wind vs price" is saved as `sa-wind-vs-price`, which is what the user will say to ask for it later.
panelsNoThe panels, rendered top to bottom. Each is one of: `{"type": "markdown", "markdown": "## Heading\n…"}` `{"type": "chart", "query": "regional_price", "title": "…", "chart_type": "line", "x": "hour", "y": ["rrp"], "color": "REGIONID"}` `{"type": "table", "query": "regional_price", "title": "…"}` `{"type": "stat", "query": "latest", "title": "…", "value_column": "rrp", "unit": "$/MWh"}` `{"type": "stats", "query": "kpis", "title": "Last 12 months", "items": [ {"value_column": "events", "label": "price events"}, …]}` — 2 to 8 numbers from one row on one compact line Add `"width": "half"` to any panel to put two side by side, and `"description"` (at most two sentences, ≤ 300 bytes) to a chart, table or stat to say what the reader should look for. `"chart_type": "calendar"` lays one measure per day out as a 53-week heatmap (`x` a date, one `y`). `"chart_type": "heatmap"` colours a two-way grid by one measure: `x` the columns, `color` the rows, one `y` (e.g. month by year). `"chart_type": "map"` places rows on a map coloured by one `y`, labelled by `x`: `"lat"`/`"lon"` name the coordinate columns, `"lat2"`/`"lon2"` make each row a segment (a line from bus to bus), and an optional signed `"direction"` column draws an arrow along it (+ toward lat2/lon2). `"hidden_series": ["min_price", "max_price"]` on a chart draws those `y` columns switched off (a legend click turns them on), so extremes do not flatten the axis. A table, or a calendar chart, may carry drill-through `links`: `{"type": "table", …, "links": [{"column": "DUID", "dashboard": "unit-detail", "params": {"duid": "DUID", "start": "$start"}}]}` — each cell of `column` (each day, on a calendar) opens that dashboard with its parameters taken from the clicked row (a column name) or from this page (`$param`). The target may be this dashboard itself. Call `get_dashboard_guide` before your first dashboard — it has the full vocabulary and the rules that get a save refused.
paramsNoDefaults for the variables the queries read. A variable is any ClickHouse placeholder in the SQL — `{region:String}`, `{min_mw:Float64}`, `{regions:Array(String)}`, `{day:Date}` — and gets a control on the page automatically; all it needs is a default: `{"region": "SA1", "min_mw": 100, "regions": ["SA1", "VIC1"]}` A value may be an object instead, adding `options` (the only values allowed — the control becomes a dropdown), `label`, `description`, or `"hidden": true` (no control; a click sets it, e.g. a calendar's day): `{"region": {"default": "SA1", "options": ["NSW1", "QLD1", "SA1", "TAS1", "VIC1"], "label": "Region"}}` For a list that changes over time (units, stations, participants), give `options_query` instead of `options`: a standalone SELECT returning a `value` column and optional `label`, re-read whenever the page opens: `{"duid": {"default": "HAMISF1", "options_query": "SELECT DUID AS value, concat(DUID, ' – ', STATION_NAME) AS label FROM semantic.duid WHERE FUEL_TYPE = 'Solar' ORDER BY DUID"}}` Values are bound by ClickHouse, never pasted into the SQL. The older list form (`[{"name": "region", "type": "enum", …}]`) still works.
queriesNoThe named SQL queries this dashboard runs, each `{"name": "regional_price", "sql": "SELECT …", "description": "…"}`. Add `"partial_day_ok": true` to a query whose daily series is meant to end on today's part-day, and the save stops warning about it. `name` is lowercase letters, digits and underscores; panels reference it. One query can feed several panels and is executed once per page view. Every query must be a single read-only SELECT/WITH over `consolidated`, `semantic` or `calculated` — never `raw_*` and never `scratch.*`. All of them are executed before the dashboard is saved. Nothing is stored if any fails.
seo_titleNoThe search-result title for the dashboard's public page, when it should say more than `title` (at most 60 characters). `title` names the dashboard and its URL, so this is how a listed dashboard gets a better search title without moving its URL. Omit it and the page uses `title`.
question_idNo
meta_descriptionNoThe snippet under the public page's search result (at most 155 characters). Omit it and the page uses the opening of its prose.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / params / description
      Previous value: -"Defaults for the variables the queries read. A variable is any\nClickHouse placeholder in the SQL — `{region:String}`, `{min_mw:Float64}`,\n`{regions:Array(String)}`, `{day:Date}` — and gets a control on the page\nautomatically; all it needs is a default:\n  `{\"region\": \"SA1\", \"min_mw\": 100, \"regions\": [\"SA1\", \"VIC1\"]}`\nA value may be an object instead, adding `options` (the only values\nallowed — the control becomes a dropdown), `label`, `description`, or\n`\"hidden\": true` (no control; a click sets it, e.g. a calendar's day):\n  `{\"region\": {\"default\": \"SA1\", \"options\": [\"NSW1\", \"QLD1\", \"SA1\",\n    \"TAS1\", \"VIC1\"], \"label\": \"Region\"}}`\nValues are bound by ClickHouse, never pasted into the SQL. The older\nlist form (`[{\"name\": \"region\", \"type\": \"enum\", …}]`) still works."New value: +"Defaults for the variables the queries read. A variable is any\nClickHouse placeholder in the SQL — `{region:String}`, `{min_mw:Float64}`,\n`{regions:Array(String)}`, `{day:Date}` — and gets a control on the page\nautomatically; all it needs is a default:\n  `{\"region\": \"SA1\", \"min_mw\": 100, \"regions\": [\"SA1\", \"VIC1\"]}`\nA value may be an object instead, adding `options` (the only values\nallowed — the control becomes a dropdown), `label`, `description`, or\n`\"hidden\": true` (no control; a click sets it, e.g. a calendar's day):\n  `{\"region\": {\"default\": \"SA1\", \"options\": [\"NSW1\", \"QLD1\", \"SA1\",\n    \"TAS1\", \"VIC1\"], \"label\": \"Region\"}}`\nFor a list that changes over time (units, stations, participants), give\n`options_query` instead of `options`: a standalone SELECT returning a\n`value` column and optional `label`, re-read whenever the page opens:\n  `{\"duid\": {\"default\": \"HAMISF1\", \"options_query\": \"SELECT DUID AS\n    value, concat(DUID, ' – ', STATION_NAME) AS label FROM\n    semantic.duid WHERE FUEL_TYPE = 'Solar' ORDER BY DUID\"}}`\nValues are bound by ClickHouse, never pasted into the SQL. The older\nlist form (`[{\"name\": \"region\", \"type\": \"enum\", …}]`) still works."
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say it is a non-read-only, non-destructive, non-idempotent write; the description adds the traits that actually matter: a save REPLACES rather than merges the spec, renaming changes the URL, all queries execute before anything is stored with every validation error returned at once, and heavy saves can be slow. It also documents timeout recovery in detail (re-check `revision`/`last_save`, no reason is stored on refusal, retry with a narrower widest range), which no annotation conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the identity of the tool, the sibling exclusion, and the edit flow come first, and recovery edge cases come last. The only waste is mild duplication of panel-type vocabulary that also appears in the `panels` schema description, which inflates length without adding new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter authoring tool with no output schema, it covers what an agent needs end to end: the spec model, the pre-save validation contract, the return value (`url`), and what to do on timeout. It also points to `get_dashboard_guide` for the full vocabulary it deliberately does not inline, so the remaining detail has a stated destination.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 90%, so the per-parameter docs already carry most semantics, and much of the description's panels/queries guidance restates schema text. What it genuinely adds beyond the schema is cross-parameter behavior: `name` + a different `title` renames and moves the URL, and the design intent behind `params`/`links` for what should not be duplicated into separate dashboards.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource and defines the artifact precisely: a live page hosted at a stable URL whose panels re-run queries on each open. It explicitly contrasts with the nearest sibling (`share_artifact` publishes a one-off PUBLIC write-up; a dashboard is private, live, editable), so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives literal user phrasings that select this tool ("build me a dashboard", "add a chart to my Y dashboard"), names the sibling it is not, and prescribes the edit flow (call `get_dashboard` first, pass its `name` with the complete spec). It also resolves two ambiguous design choices: use `params` rather than one dashboard per region, and use one dashboard plus a table `links` entry rather than a dashboard per row.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.