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 running the exact npx … upgrade command 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 and materialized views in the QuestDB database

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

Get the runtime details/statistics of a specific table or materialized 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) and the layout into a NEW notebook labelled " (copy)" placed right after the original; cell ids are regenerated and last-run results are cleared. 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. 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, UI flags, chart config, last-run status + trimmed error). 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. 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, kind via type, last-run statuses). 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. 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/h are integers in the react-grid-layout grid. The 12-column limit applies to WIDTH only (w ≤ 12); h is NOT in column units — the rendered cell box is h10 + (h-1)20 px (10px rows with 20px gaps BETWEEN rows; do NOT estimate with h30), and a fixed 44px cell header inside it leaves (h30 - 64)px of content. Chart cells pad the plot a further ~40px top and ~56px bottom (~86px when the zoom slider shows) inside that content area. EXAMPLES: markdown h:3 -> 310 + 220 = 70px box, 70 - 44 = 26px of text (the minimum strip); markdown h:5 -> 130px box, 86px of text (a comfortable title); chart h:10 -> 280px box, 236px content, ~140px of plot after padding (~110px with the zoom slider).

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 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 ("1s", "5s", "10s", "30s", "1m"), 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 ("1s", "5s", "10s", "30s", "1m"). 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.

Toggle whether the cell's result view (chart OR table) fills the cell, hiding the editor. Applies to any cell that has a result — not just charts. For narrow cells, there is no split-view. When this is false, the cell only shows the editor for narrow cells. For wide cells, it shows the editor and the result view if result exists.

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. 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 each 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. 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 each 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.