build_chart
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
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X-axis column name. Must exactly match an entry in `columns`. Omit only for `table` / `summary`. | |
| y | No | One or more Y-axis column names, each matching an entry in `columns`. Multiple y columns render as separate series. | |
| lat | No | `map` only (#2711): the latitude and longitude columns that place each row, or start its segment. Both required for a map. | |
| lon | No | ||
| lat2 | No | `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. | |
| lon2 | No | ||
| rows | No | Row 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. | |
| color | No | Optional 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. | |
| title | No | Chart title shown to the user. Optional (#1899): defaults to an inferred "{measures} by {x}" title when omitted. | |
| columns | No | Column 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_label | No | Optional 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. | |
| direction | No | `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_id | No | PREFERRED: 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_type | No | `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_id | No | Optional UUID returned by an earlier `start_question` call. When provided, this tool call is attributed to that question. | |
| column_types | No | Optional 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_labels | No | Optional 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_shape | No | Optional 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. |