Tool reference

“Discover the data. Call with no arguments first for an overview of the data source: the most-connected tables and a total count. Pass search to find tables related to a concept when you don’t know the exact name, table for one table’s full detail (columns, types, row count, sample rows), or full: true to list every table. Table and column names are shown exactly as they must appear in SQL, already quoted where the database requires it. Paste them verbatim; do not add, remove, or change quoting or case.”

“The user can edit this data source’s context, so the overview also reports its gaps and each table’s key, and a table’s detail gives each description, key, time column and join a from (edit, source or catalog), with * where the draft changes it, plus the drafted description, key or time column.”

“Find tables when you don’t know the exact name: by concept, keyword, or column. Takes precedence over table and full.”

“Execute a single read-only SQL SELECT and return rows. Discover names with explore_schema first. Results are capped; add LIMIT/OFFSET to page. Prefer aggregating or filtering in SQL over pulling raw rows: the preview shows at most 250 of them, while the whole bounded result (up to 5000 rows, or 500000 with max_rows) is fetched and captured regardless of what the preview carries. When returned, resultRef identifies the captured bounded rows; pass it to create_export_file instead of rerunning SQL. Set capture_only: true when you only need that reference, to skip the row preview, and max_rows when the capture needs more rows than the standard ceiling holds. Table and column names are shown exactly as they must appear in SQL, already quoted where the database requires it. Paste them verbatim; do not add, remove, or change quoting or case. Dialect: PostgreSQL. Identifier quote: “double quotes”. Dates: date_trunc(‘month’, col), now() - interval ‘7 days’. Cast: col::type. Nulls: coalesce(a, b).”

“Render one chart, or a carousel of up to 10, and show them to the user. Each entry in charts is either a chart the user saved ({ chart_id }) or a chart drawn from a read-only SQL SELECT now ({ sql, chartType?, title?, encode?, fields?, … }); the two kinds mix freely. The input is always {“charts”:[…]}, even for one chart. One entry shows one chart; two or more show a carousel the user pages through in the order given. For an ad-hoc chart, consider running the query through sql_query first to check the shape of the results. Charts take no params: write literal values. The reply summarises what was drawn with a row preview; the user sees the whole chart. Every chart returns its own resultRef and snapshotRef; pass one to create_export_file to download that chart’s data or image, or to save_chart to keep the chart. The charts the user saved are listed by explore_charts. Dialect: PostgreSQL. Identifier quote: “double quotes”. Dates: date_trunc(‘month’, col), now() - interval ‘7 days’. Cast: col::type. Nulls: coalesce(a, b).”

“A native JSON array of 1 to 10 charts, never a JSON-encoded string. Each entry is either { chart_id } for a chart the user saved, or { sql, chartType?, title?, encode?, fields?, … } for a chart drawn from a query now; the two kinds may mix. Stacking, horizontal bars, a secondary axis, a line over bars, the x-axis scale, reference lines, axis titles and the funnel style apply to some types only: the type’s docs page lists exactly what it takes, and an option that does not fit the type is rejected with the valid list.”

“Map columns to the chart: x is the single column for the x-axis, y one measure or a list, series a column to split one measure by. Set x whenever more than one column could plausibly be it, e.g. SELECT COUNT(*) AS n, year FROM t GROUP BY year (set x: “year”), where a wrong guess would plot the count instead. encode.line and encode.y2 mix a line into bars or add a secondary axis: see the type’s docs page.”

“Loads a rendered chart or dashboard’s data into the chart widget, or re-renders a dashboard for a filter pick. For the widget only: to see a chart, call render_chart or render_dashboard.”

“Create a CSV (csv, or gzip-compressed csv.gz) from one resultRef or a PNG from one snapshotRef without rerunning the query. The file holds exactly the rows its capture holds, including a bulk capture taken with sql_query max_rows. resources/read the returned artifactUri to get the exact bytes, then open, save, or use it in the workspace.”

“Save a dashboard for this user, or edit one they already saved. The id it is stored under is returned; render it with render_dashboard and that id. Omit dashboard_id to create a new one, and send one replace_all with title, a one-line description and items, the tiles in display order: {“operations”:[{“op”:“replace_all”,“title”:“Sales”,“description”:“Revenue by month.”,“items”:[…tiles]}]}. Every change goes inside operations; nothing else sits at the top level beside dashboard_id and expected_version. To edit, pass that dashboard_id together with the expected_version from the last save (or from explore_dashboards), which is refused if someone else changed it first. Read the dashboard first with explore_dashboards and its dashboard_id: an edit replaces the whole tile, so pass its SQL back unless you mean to change it. A version_conflict means it changed: re-read it and reapply your change. Chart and KPI options: docs charts/<type> (e.g. charts/line) and charts/kpi; params and optional [[ ]] filters: docs dashboards/params; open them directly, e.g. explore_docs({“topic”:[“charts/kpi”,“charts/line”]}). The SQL of the tiles you add or edit is run once as you save, and any that fail are named in the reply; the save succeeds either way, and render_dashboard shows each error in place. Dialect: PostgreSQL. Identifier quote: “double quotes”. Dates: date_trunc(‘month’, col), now() - interval ‘7 days’. Cast: col::type. Nulls: coalesce(a, b).”

“Which edit to make, and what the other fields mean. add takes items (exactly one tile), placement; edit takes id, items (exactly one tile); move takes id, placement; remove takes id; set_metadata takes title, description, columns, params; replace_all takes items, title, description, columns, params. A field that belongs to another op is rejected, as is a missing one.”

“The tiles, always an array, even for one: {“op”:“edit”,“id”:“by_month”,“items”:[{“kind”:“chart”,“id”:“by_month”, …the complete tile}]}. add: the one tile to add. edit: the one replacement tile, whose id must equal id. replace_all: the complete new set of tiles, in display order. Every tile has kind (chart, kpi or text), an id (lowercase letters, digits, _ and -, starting with a letter, at most 64 characters; edit, move, remove and placement refer to tiles by it) and an optional span. A dashboard holds at most 16 chart/KPI tiles, counted across the whole dashboard once your batch is applied; text tiles do not count. Rename a chart tile with an edit that changes its title, a KPI with its title; rename the dashboard with set_metadata.”

“Map columns to the chart: x is the single column for the x-axis, y one measure or a list, series a column to split one measure by. Set x whenever more than one column could plausibly be it, e.g. SELECT COUNT(*) AS n, year FROM t GROUP BY year (set x: “year”), where a wrong guess would plot the count instead. encode.line and encode.y2 mix a line into bars or add a secondary axis: see the type’s docs page.”

“How many of the 4 grid columns this tile spans, 1 to 4; 4 is full width and 2 half. A chart or text tile added without a span gets 2, a KPI 1, and an edit that omits span keeps the tile’s width. columns is ignored: the grid is fixed at 4.”

“Permanently delete one of this user’s own saved dashboards. Only dashboards they saved themselves can be deleted; verified dashboards and dashboards shared with the user are not yours to remove. Pass the expected_version from explore_dashboards or the last save, which is refused if it has changed since. This cannot be undone, so confirm with the user first.”

“Save a chart for this user, or edit one they already saved. To save the chart render_chart just showed, pass its snapshotRef (or resultRef, or the viewRef of a single chart) and a title (an optional description helps you find it again later via explore_charts); the chart is stored exactly as it was drawn and its id is returned. To edit, pass that chart_id with the expected_version from the last save or from explore_charts (refused if it changed since), and the new title/description and/or a reference from a fresh render_chart with the new query. References last 30 minutes; after that, render the chart again and save the new reference. One chart per call: to keep several charts from a carousel, call save_chart once for each.”

“List the charts this user saved (id, title, description, chart type, version). Show one with render_chart and its chart_id, edit or delete it with the version reported here. Pass chart_id to read one chart instead of the list; that returns its full definition, the SQL and the chart options included, in the exact shape render_chart takes as an entry. Dashboards are separate: explore_dashboards lists those.”

“Permanently delete one of this user’s own saved charts. Pass the expected_version from explore_charts or the last save, which is refused if it has changed since. This cannot be undone, so confirm with the user first.”

“How-to docs for charts (render_chart) and dashboard params and KPIs (save_dashboard). The pages are fixed: charts (choosing a type), charts/<type> for line, bar, area, pie, scatter, funnel, waterfall and table (the options that type takes), charts/kpi and dashboards/params. Only when asked for them: charts/styling (colours, dashed lines, markers, highlight, legend) and charts/annotations (target, average and median lines, bands, trend lines and moving averages). Open the pages you need directly with topic, several at once as a list; search with query only when you do not know which page. Each page ends with examples that validate.”

“For editing this data source’s context: context/runbook, context/descriptions, context/joins, context/keys-and-time, context/metrics and context/publishing. Open context/runbook first.”

“A page id: “charts”, “charts/<type>” for line, bar, area, pie, scatter, funnel, waterfall or table, “charts/styling”, “charts/annotations”, “charts/kpi” or “dashboards/params”; add #section to open a page at a section, or pass a list of up to 4 ids. Takes precedence over query.”

“List the available dashboards (id, title, description, params). Call this first to discover what you can render, then call render_dashboard with a chosen dashboard_id. Pass dashboard_id to read one entry instead of the list; for a dashboard the user saved themselves that returns its full definition, every tile’s SQL included, which is what save_dashboard needs to edit it. For a dashboard that takes params, the detail read also lists each param’s description, default and up to 50 sample values. A param marked clearable is used only inside [[ ]] optional clauses, so it can show All; that is derived from the SQL, not something you set. Pass item_id to re-render a single chart cell by its id (ids appear in the dashboard summary), with preview_rows for its rows.”

“Render one dashboard by dashboard_id. This displays it to the user directly, as an interactive chart or grid of tiles. Pass item_id to re-render a single chart cell by its id (ids appear in the dashboard summary), with preview_rows for its rows. When returned, resultRef and snapshotRef identify captured item data and render specs; pass one to create_export_file instead of rerunning the dashboard. Call explore_dashboards for the dashboards this user can render, the user’s own saved ones included; verified dashboards are listed first.”

“Lists and searches one dashboard filter’s values for the dashboard widget’s filter menu. Not for answering questions: to see a dashboard’s params and sample values, call explore_dashboards with its dashboard_id instead.”

“Lists this data source’s context versions, the draft on top, and the changes in any one of them. Call with no arguments first, then with a version for the tables and metrics it changed, an object for that one’s changes, and a field for one change in full. Read explore_docs context/runbook before editing.”

“Edits this data source’s context draft: descriptions, keys, time columns, which tables AI clients see, joins and metrics, up to 100 operations in one call. Nothing is served to anyone until the draft is published. Each operation is checked on its own, so a refused one leaves the others applied. Read explore_docs context/runbook before editing.”

“set_description { table, column?, description }, set_key { table, columns }, set_time_column { table, column }, set_visible { table, visible }, add_join { table, to, pairs }, remove_join { table, to, pairs?, confirmed? }, create_metric { name, description?, calculation?, instructions? }, update_metric { metric, name?, description?, calculation?, instructions? }, remove_metric { metric, confirmed? }, remove_change { change } or { object }, revert_change { change, version, confirmed? }.”

“Publishes this data source’s context draft as a new version, so every AI client that reads the data source sees it. Pass the draftRevision from get_versions or edit_draft; a draft that changed since is refused with what changed. Works only once an admin allows publishing from AI clients in Settings › AI tools. Read explore_docs context/runbook before publishing.”