Skip to main content
Glama

NEM Explorer (ScadaMiner)

build_chart

Read-onlyIdempotent

PREFERRED INPUT: pass the result_id from an execute_sql response instead of columns/rows — the chart is then built from ALL rows of the result server-side (full fidelity, zero retyping). Inline columns/rows are only for small results that carried no result_id. Construct a web-ready Plotly chart spec from a query result. Pass the columns and rows from an execute_sql (or run_capability) result verbatim, plus the chart intent: chart_type (line/bar/area/scatter/pie/box/table/summary), title, x, one or more y columns, and optionally color (a grouping column — produces a stacked bar), y_label, series_labels, and analysis_shape (timeseries/distribution/ranking/breakdown/comparison/single_value). Legend entries are named after their y column unless you pass series_labels (one per y, same order). Column names are SQL identifiers, so whenever the label you want carries punctuation — % profitable, k=1.0, p95 dispatch error (MW), $/MW/yr — pass it in series_labels; a column alias cannot hold it. Only rows is truly required: columns may be omitted if you pass rows as JSON objects keyed by column name, and chart_type, title, x and y are all optional — when omitted they are inferred from the data shape (a line for a time/period axis, otherwise a bar, falling back to a table when the data isn't chartable). Supplying them is still preferred when you know the intent. Returns a renderer-tagged spec ({renderer, title, figure}) ready to hand to a Plotly frontend — identical to what the chat product renders, so no conversion is needed. A figure too big to inline (dozens of traces, thousands of points) comes back as a handle instead: chart_id, chart_url (the spec as JSON), a one-line summary and an outline of its traces and axes. Every column you reference in x/y/color must exist in columns. Use this after you've fetched data and the user wants a visualization (run_capability with execute:true already returns a chart_figure for capability results). To share or present a chart (or several), pass the returned spec(s) to share_artifact — do not build a PDF or slide deck locally.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "build_chart"
  }
}

Input Schema

NameRequiredDescriptionDefault
xNoX-axis column name. Must exactly match an entry in `columns`. Omit only for `table` / `summary`.
yNoOne or more Y-axis column names, each matching an entry in `columns`. Multiple y columns render as separate series.
latNo`map` only (#2711): the latitude and longitude columns that place each row, or start its segment. Both required for a map.
lonNo
lat2No`map` only: the far end of each row's segment. With these each row is a straight line (a transmission line from bus to bus); without, a point.
lon2No
rowsNoRow values. Either positional arrays aligned to `columns` (the `execute_sql` / `run_capability` shape — pass verbatim), or JSON objects keyed by column name (in which case `columns` may be omitted). Mixing is fine; objects are projected onto the resolved column order.
colorNoOptional grouping/series column (e.g. region, fuel type). Matched case-insensitively against `columns`. On a bar chart this groups the bars; the renderer stacks only additive measures such as totals, counts, energy, or capacity.
titleNoChart title shown to the user. Optional (#1899): defaults to an inferred "{measures} by {x}" title when omitted.
columnsNoColumn names of the query result, in the same order as each row's values — only for data you hold inline (a result small enough that no result_id was issued). Optional (#1834): when omitted and `rows` are JSON objects, the object keys are used as the column set.
y_labelNoOptional y-axis label override (e.g. "Generation (MWh)"). **Required** when the single `y` column is a metric you derived in SQL whose alias names no subject — `ratio`, `share`, `value`, `pct`, `total`: the axis would read "Ratio", which never says ratio of what, in what unit (#2180). A `title` that names the metric ("Raise:lower regulation dispatch ratio by renewable output") is accepted in its place.
directionNo`map` only: a signed column that puts an arrowhead on each segment, pointing from (`lat`, `lon`) to (`lat2`, `lon2`) above zero and back below zero. For which way power flows.
result_idNoPREFERRED: the `result_id` an `execute_sql` response returned. The chart is then built server-side from ALL rows of that result — full fidelity, and you never retype data. When set, `columns` and `rows` are ignored. (#2355)
chart_typeNo`line` | `bar` | `area` | `scatter` | `pie` | `box` | `heatmap` | `map` | `table` | `summary`. `x` and at least one `y` are required for every type except `table` and `summary`. A `heatmap` also needs `color` (its rows; `x` gives its columns) and colours each cell by the first `y`. A `map` also needs `lat` and `lon` (optionally `lat2`/`lon2` for segments and `direction` for arrows); `x` labels each row and the first `y` colours it. Optional (#1899): when omitted, a chart_type (and any omitted `x`/`y`) is inferred from the data shape — a line for a time/period axis, otherwise a bar — falling back to a table when the data isn't chartable.
question_idNoOptional UUID returned by an earlier `start_question` call. When provided, this tool call is attributed to that question.
column_typesNoOptional ClickHouse column types aligned with `columns`, copied from the `column_types` field of the originating `execute_sql` / `run_capability` result. When present they are the authoritative signal for which columns are temporal vs numeric vs categorical, so passing them produces a more reliable chart than inferring from column names alone.
series_labelsNoOptional legend labels, one per entry of `y` and in the same order. Without these a series is named after its column, and a column name is a SQL identifier — `pct_profitable_k_1_0` reads back as "Pct Profitable K 1 0". Pass `["% profitable, k=1.0", ...]` to keep the punctuation, units, and casing you meant (#2216). Blank entries and short arrays fall back to the column-derived name. With a single `y` (no legend) the label titles the y axis instead.
analysis_shapeNoOptional analytical shape hint: `timeseries`, `distribution`, `ranking`, `breakdown`, `comparison`, or `single_value`. This tells the typed chart selector what analysis you intended; definitive ClickHouse column types still win if axes contradict the data.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantial behavioral detail beyond them: the exact return shape (`{renderer, title, figure}`), the large-figure fallback (`chart_id`, `chart_url`, `summary`, `outline`), server-side full-fidelity building from `result_id`, and inference fallbacks for omitted `chart_type`/`x`/`y` (line for time axes, bar otherwise, table when unchartable). Nothing contradicts the annotations.

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?

The description is front-loaded with the most important instruction ('PREFERRED INPUT: pass the `result_id`...') and every sentence adds information. However, it is delivered as one dense block and repeats some concepts (the result_id-versus-inline-data distinction appears twice), which slightly hurts scanability for an 18-parameter tool.

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 an 18-parameter tool with no output schema, the description covers what is needed to call it correctly: preferred input mode, fallback mode, return format including the oversized-figure handle, inference defaults, column-reference validation, legend-label behavior, and downstream routing to `share_artifact`. There are no major gaps for an agent to guess at.

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

Parameters5/5

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

Although schema coverage is high (89%), the description adds critical meaning the schema does not: `result_id` as the preferred input that causes `columns`/`rows` to be ignored, `series_labels` to preserve punctuation/units that SQL aliases cannot carry, `y_label` being effectively required when a derived metric alias names no subject, `column_types` as the authoritative temporal/numeric signal, and `analysis_shape` as a hint to the typed chart selector. This is well beyond the structured field definitions.

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?

The description opens with a specific verb and resource: 'Construct a web-ready Plotly chart spec from a query result.' It distinguishes itself from siblings by naming `execute_sql`/`run_capability` as the data source and `share_artifact` as the downstream step, and it states the preferred input (`result_id`) versus the fallback (inline columns/rows), so an agent can identify the tool without opening the 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?

It gives explicit when-to-use guidance ('Use this after you've fetched data and the user wants a visualization'), names the alternative that already returns a chart (`run_capability` with `execute:true`), and explicitly warns against building a PDF or slide deck locally. It also states when inline columns/rows are acceptable versus when `result_id` must be used.

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.