Get the credentials the user needs to pair their browser with this MCP bridge — calling this tool does NOT itself pair anything. It returns a deep_link, ws_url, token, AND a pre-rendered userMessage with the exact text to show the user. REQUIRED FLOW — do all three in the defined: (1) call this tool, (2) write a message to the user containing the userMessage text (or your own equivalent showing deep_link + ws_url + token), (3) call wait_for_pairing. DO NOT skip step (2). Calling wait_for_pairing without first showing the credentials guarantees a timeout — the user has no credentials to enter, so they cannot pair. By default this also auto-opens the deep link in the user's default browser; pass auto_open_browser:false to suppress that and just return the credentials. Returns paired:true if already paired.

Poll for completion of pairing started by get_pairing_credentials. PREREQUISITE: you have already written a message to the user containing the deep_link + ws_url + token from get_pairing_credentials's last response. If you have NOT yet shown those credentials, do that first — calling this tool without showing credentials only burns 50 s of polling while the user sees nothing actionable. Blocks for timeout_ms (default 50 s, max 50 s — sized to fit under typical MCP client tool-call timeouts). Returns {paired:true, consoleOrigin, permissions:{grantSchemaAccess,read,write}} on success, or {paired:false, reason:'timeout', retryCount, maxRetriesHint:10} on timeout — call again to keep waiting (up to ~10 retries / ~8 min) until the user pairs. If the bridge version doesn't match what the web console expects, the success payload includes a warning, a pre-rendered userMessage, and assistantNextActions; you MUST show the userMessage to the user verbatim AND suggest the exact upgrade instruction it contains (offer to run it for them) before proceeding. If pairing is refused outright for an incompatible bridge, the result is {paired:false, reason:'incompatible_bridge', userMessage, assistantNextActions} — show the userMessage verbatim and STOP polling; pairing cannot succeed until the user reinstalls the bridge version named in the message. permissions describes the user-granted MCP scopes: grantSchemaAccess=true allows schema introspection (tables/columns); read=true allows DQL (SELECT/SHOW); write=true additionally allows DDL/DML (CREATE/INSERT/UPDATE/DELETE/DROP/…). Operations outside the granted scope return PERMISSION_DENIED with a message naming the missing scope — adjust your plan accordingly rather than retrying.

Get a list of all tables, materialized views, views and live views in the QuestDB database

Get the full schema definition (DDL) for a specific table, materialized view, view or live view

Get the runtime details/statistics of a specific table, materialized view, view or live view

Validate the syntax correctness of a SQL query using QuestDB's SQL syntax validator. All generated SQL queries should be validated using this tool before responding to the user.

Get a table of contents listing all available QuestDB functions, operators, and SQL keywords. Use this first to see what documentation is available before requesting specific items.

Get documentation for specific QuestDB functions, operators, or SQL keywords. This is much more efficient than loading all documentation.

Create a new QuestDB notebook tab in the editor. You never see query data; this only scaffolds the tab and binds the current chat if it isn't already bound to a notebook. The tab is ALWAYS created in the background — you never switch the user's active tab. The user sees a notification and opens it themselves; only call activate_notebook if they explicitly ask to be taken there.

Switch the user's editor to the given notebook tab so it becomes visible and focused. ONLY call this after the user has explicitly agreed to be taken to the notebook (e.g. they accepted your offer to open it). Never call it to auto-switch while the user is working elsewhere.

Duplicate a notebook tab. Copies every cell (SQL, mode, chart config), layout, and run history into a NEW notebook labelled " (copy)" placed right after the original; cell ids are regenerated. Matching saved result snapshots are copied best-effort in the background and hydrate when the copy is opened. last_run_status is preserved as history and does not guarantee that a saved result snapshot exists. The copy is ALWAYS made in the background — you never switch the user's active tab. The user sees a notification and opens it themselves; only call activate_notebook if they explicitly ask to be taken there.

Archive (soft-delete) a notebook tab — the same as the user closing it with the X. It moves to history and the user can restore it; it is not permanently destroyed and query data is untouched. If this notebook is bound to the current chat, the binding goes stale (start a new one with create_notebook).

List the cells in a notebook. Returns id, type, short preview (≤120 chars), position, mode, and last-run status. Mode is the presented result kind: run for a table result, draw for a chart, and null for editor-only/markdown cells. Three fields are LIVE-ONLY — present only while the notebook is open in the console, so absence never means "not refreshing" or "not blocked": refreshing: true while a refresh is in flight (the visible rows are still the previous round's), last_refresh_error when the last round left a failure, and auto_refresh_blocked: "contains_write" on cells auto-refresh will not run. last_run_status is unrelated to these: it stays the outcome of the last completed RUN, and a refresh never changes it. No cell data values.

Get full details of a cell (value, kind via type, editor_height/result_height, view, chart config, last-run status + trimmed error). Height values are fixed CSS pixels or "auto". view reports what a SQL/draw cell presents: "editor" while there is nothing to show, else the stored result or editor_result arrangement. Markdown has no pane-view state: it reports view and result_height as null. Other LIVE-ONLY fields are refreshing: true, last_refresh_error, and auto_refresh_blocked: "contains_write"; absence never means "not refreshing" or "not blocked". last_run_status is unrelated to refresh state: it stays the outcome of the last completed RUN. type:"markdown" marks a prose cell whose value is markdown source; SQL cells omit type. Never includes query result data. By default the value is capped at 4 KB; a capped response carries truncated: true and full_length. A truncated value is NOT the cell's real content — NEVER write it back (update_cell / apply_notebook_state value); re-read with get_full_content: true first, or keep the cell with preserve_value: true.

Full structural snapshot of a notebook (layout, cells with previews, semantic pane dimensions, kind via type, last-run statuses). Cell grid contains x/y/w only; height is derived from editor_height, result_height, and view. view reports what a SQL/draw cell presents: "editor" while there is nothing to show, else the stored result or editor_result arrangement. Markdown has no pane-view state: it reports view and result_height as null. Other LIVE-ONLY fields are refreshing: true, last_refresh_error, and auto_refresh_blocked: "contains_write"; absence never means "not refreshing" or "not blocked". last_run_status is unrelated to refresh state: it stays the outcome of the last completed RUN. auto_refresh_default is omitted when the notebook has no configured default. type:"markdown" marks a prose cell; SQL cells omit type. No cell data values; no columns/rows/count. Previews are capped at 120 chars — cells cut carry preview_truncated: true + full_length; a preview is never a cell's real content to write back.

Append a cell to the notebook. Returns the new cell id and, if run=true, a per-query status array with the same semantics as run_cell (reads run in parallel; an invalid statement is skipped with its error). Writes are never auto-run: a cell containing DDL/DML comes back { ran: false, skipped: true }. You never see query rows or column data. Set type:"markdown" to add a prose cell instead of a SQL cell — its sql field then carries the markdown source, it is rendered (never executed), and run is ignored.

Replace a cell's value. Overwrites preemptively — cells are auto-saved. Results carry over by content: a statement whose text is unchanged keeps its result and its refresh state, an edited or added one starts empty, and a rewrite that leaves no statement unchanged clears the cell's results. Use to fix a broken SQL cell. When editing part of a long cell, base the new value on a non-truncated read (get_cell with get_full_content: true) — never on a preview or a truncated: true read.

Delete a cell from the notebook.

Swap a cell with the one above it.

Swap a cell with the one below it.

Duplicate a cell immediately after the original.

Execute a SQL cell. A cell whose statements are all reads runs them in PARALLEL: one failure skips nothing, and a statement the server rejects at validation is skipped with its validation error as that statement's result. A cell containing any DDL/DML runs sequentially instead, and a failure stops the remaining statements. Returns { success, queryCount, results: string[] }, where each results entry is "success", "cancelled", or "ERROR: <message>", in source order. You do NOT see columns, rows, or values — call run_query if you need data. success is true only when every statement reached "success". This is the ONLY path that executes agent-initiated DDL/DML in a cell (apply_notebook_state and add_cell never auto-run writes) — it requires the 'write' permission and the user's consent. A markdown cell is never executed: the response is { ran: false, skipped: true, note: <reason> }.

Switch a notebook between list and grid layouts.

Position a single cell in grid mode. x/y/w are integers in the react-grid-layout grid; width is limited to 12 columns. Cell height is derived from its semantic pane dimensions. The response includes the applied grid position plus the cell's presented view and mode; editor-only and markdown cells report mode null, and markdown also reports view null. Use set_cell_dimensions to resize a cell or change its view.

Resize a cell using semantic pane dimensions in CSS pixels and choose its pane view. Every input field is required by strict tool calling: pass null to preserve the current setting. Pass "auto" for a height to restore automatic sizing, or a number to pin it. For SQL/draw cells, view accepts editor, result, or editor_result. view "editor" is DESTRUCTIVE: it discards the cell's result and snapshot and clears its presented mode — the same gesture as toggling off the table or chart in the UI; the response then carries mode:null and result_discarded:true. The stored result/editor_result arrangement is kept for the next result. A cell with nothing to show reports view "editor" and mode null. Markdown has no pane-view state: it reports view, mode, and result_height as null; editor_height sizes its rendered content, while result_height and view are ignored — keep them null. Use 86px for a polished markdown title. Chart result_height must be at least 296px; table results at least 100px. No pane may exceed 2400px.

Switch a SQL cell between run (table output) and draw (chart output). Draw cells auto-execute — do not call run_cell afterwards. MULTI-SERIES TIP: a draw-mode cell can hold multiple SELECT statements separated by ;. The first query's timestamp column is the chart's x-axis (the 'anchor'); every additional query contributes its numeric columns as extra series merged on the time axis. Use this to overlay metrics that come from different tables or different aggregations on a single chart.

Configure the chart for a draw-mode cell. The cell's ;-separated SELECTs AUTO-COMBINE into one chart sharing the first query's x-axis; queries holds one config per statement (index-aligned). Queries combine when their x-axis kind matches: all-temporal merge by time, all-categorical merge by category name. Each query keeps its own type (line/area/stepLine/stepArea/bar/stackedBar/scatter/pie/candlestick); set axis:"right" (+ optional right_axis) for a series on a different unit/scale; enabled:false opts a query out (the first query is always included — it defines the x-axis). For a candlestick query, supply ohlc:{open,high,low,close} (required — a candlestick needs an explicit ohlc mapping). When x_column is a NUMERIC column (not a timestamp/category) it renders as a continuous value axis. Numeric-x charts are single-query (they don't combine). Patch semantics: top-level x_column/right_axis null = preserve; queries null = preserve; queries: [] clears overrides (back to inference); a non-null queries array REPLACES all per-query configs (send one entry per ;-split statement — a non-empty array whose length differs from the statement count is rejected). pie/scatter/stackedBar only render as a chart of their own (single-query).

Set or clear the highlight rules of a run-mode cell's result grids (trend coloring): flash cells that moved up or down since the previous refresh, color threshold breaches, band values into steps, or shade a range. One config per cell, applied to every statement's grid by column name; a grid without the column is not affected. Replaces the whole config (PUT). highlight_config: null clears it. Typical watchlist: identity_columns ["symbol"], rules [{kind:"previous",column:"price",op:"gt",color:"green"},{kind:"previous",column:"price",op:"lt",color:"red"}]. Pair with set_cell_autorefresh so the grid ticks. Colors are hue names (theme-aware): red, teal, amber, lime, orange, purple, green, pink, blue, olive; red and green are the loss/gain pair.

Set auto-refresh polling for a cell, as a per-cell override of the notebook default (set_notebook_autorefresh). Applies to both chart (draw-mode) and grid (run-mode) cells. A cell containing DDL/DML never polls: the value is stored, but the engine blocks its ticks and read tools report auto_refresh_blocked: "contains_write". Markdown cells are rejected. Nothing polls without a per-cell value or a notebook default. value: true = adaptive poll (interval auto-tuned to response time), false = no polling, a fixed interval string (digits plus ms, s or m, from 50ms to 60m, e.g. "250ms", "5s", "15m"), or null to clear the override so the cell inherits the notebook default.

Set the notebook-level auto-refresh default for every cell showing a chart or a grid. Cells with no per-cell value inherit it; set_cell_autorefresh sets a per-cell override that wins over it. Cells containing DDL/DML are skipped — auto-refresh never executes a write. Until this is set, nothing polls. value: true = adaptive poll (interval auto-tuned to response time), false = no polling, or a fixed interval string (digits plus ms, s or m, from 50ms to 60m, e.g. "250ms", "5s", "15m"). reset_cell_overrides: true additionally deletes every per-cell override in the same atomic call, so ALL cells follow the new default — the equivalent of the console's "Reset cell overrides" action. Nothing re-runs; false or null leaves per-cell overrides in place and they keep winning over the default.

Set or clear a cell's name (its display label in the cell header). Applies to any cell; for a chart cell it is also the chart title. Pass null to clear.

Bulk-apply the entire desired state of a notebook in one atomic call. Use this for bulk edits spanning multiple cells or creating a notebook from scratch. Use update_cell or set_cell_* for small operations. Use INSTEAD OF chained add_cell + update_cell + set_cell_mode + set_cell_chart_config only when composing a multi-cell layout from scratch, changing many cells at once, or restructuring an existing notebook. The cells array is the COMPLETE desired list: cells in the current notebook whose id is missing from your request are DELETED. For new cells, omit id and one will be generated. Each cell carries exactly one of value (full verbatim SQL) or preserve_value: true (keep the existing cell's SQL, results, and run history unchanged). A changed value carries results over by content: a statement whose text is unchanged keeps its result, an edited or added one starts empty, and a rewrite that leaves nothing unchanged clears the cell's results — prefer preserve_value for every cell whose SQL you are not changing, and NEVER send a value reconstructed from a preview or a truncated get_cell read. Charts in mode='draw' render automatically — do not call run_cell afterwards. Cells with resolved mode='run' (explicit, or omitted: new defaults to 'run', existing preserves) auto-execute after the apply — EXCEPT cells whose statements include DDL/DML (INSERT/UPDATE/CREATE/DROP/...): those are NEVER auto-executed (their runs entry gets skipped: true), so applying state can never trigger a write's side effects. Take consent from the user, then call run_cell explicitly to execute them. Markdown cells (type:"markdown") are rendered prose and are likewise never auto-run. Auto-executed read-only cells run their statements in PARALLEL (one failure skips nothing; a statement rejected at validation is skipped with its validation error). Each cell also accepts auto_refresh — the same per-cell override set_cell_autorefresh writes. The response includes a runs: [{cellId, success, queryCount?, results?, error?, skipped?}] array — results is the per-statement status list ("success" / "cancelled" / "ERROR: <message>"); a top-level error is set only when the run was refused before any statement executed. The response also carries results_cleared: the ids of cells whose whole result this apply discarded (view:"editor", or a changed value that kept no statement unchanged); it is empty when nothing was cleared, and a cell that keeps some statement results is not listed. Always call get_workspace_state first; the state-freshness gate applies.

Spotlight one cell (or null to restore normal layout). Hides other cells in the notebook view.

Execute an arbitrary SQL statement against the user's QuestDB instance and return the result rows so you can inspect data, validate work, or compose follow-up queries. UNLIKE run_cell, this tool DOES return data values. Default limit is 100 rows; pass limit (max 10000) to request more. The response payload is capped at ~1 MB — rows beyond that are dropped from the tail. The response includes truncated, total_count, and returned_count so you know exactly what was clipped. DDL/DML (CREATE / INSERT / UPDATE / DROP / etc.) is allowed and executes against the live database — be deliberate. Auth + connection are handled by the user's already-authenticated browser session.

If notebook tools fail with BRIDGE_NOT_PAIRED, call get_pairing_credentials to begin pairing (the response includes a one-click URL to show the user; authentication runs in the browser, the bridge never sees credentials). Once paired, call get_workspace_state at the start of every notebook turn; the digest of edits since your last fetch is in get_recent_user_actions.

Return the current workspace + notebook context as text. Use this at the start of every notebook turn so you know which notebook is active, what cells exist, layout mode, chart configs, and last-run statuses. SQL/draw cells report their pane view: "editor" while there is nothing to show, else the stored result or editor_result arrangement. Their mode matches that presentation: null for editor-only, run for a table result, and draw for a chart. Markdown reports view, mode, and result_height as null. Pass include_user_events=true to also receive the digest of edits the user made since your last fetch.

If notebook tools fail with BRIDGE_NOT_PAIRED, call get_pairing_credentials to begin pairing (the response includes a one-click URL to show the user; authentication runs in the browser, the bridge never sees credentials). Once paired, call get_workspace_state at the start of every notebook turn; the digest of edits since your last fetch is in get_recent_user_actions.

Return the digest of user edits to the notebook since your last fetch (or session start). Use this to detect that the user changed something the agent might want to react to. Coalesced — multiple typing events on the same cell collapse to a single 'edited' entry.