MotherDuck

Edit a guide's markdown body by applying one or more text replacements, then save as a new version. Identify the guide by `uuid`. Reads the stored guide, applies edits in sequence, and persists. Example: {uuid: '<guide uuid>', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_guide call is needed.

edit_guide_content

Load instructions for creating MotherDuck dives. You MUST call this tool first — before generating any chart, visualization, plot, dashboard, inline graphic, or export/download control — whenever the user asks to explore, visualize, display, or export MotherDuck data, or wants a dive with buttons or forms that write, update, insert, or delete data.

get_dive_guide

Fetch a flight by UUID. Returns metadata plus a version snapshot (source code, requirements, config, secret names, token name). Omit `version` to get the current version; pass a 1-indexed version number to inspect history.

get_flight

Load the convention for making a MotherDuck flight's runs show up in the Flight Explainer, a live, step-by-step view with per-step timing. Use section only for a narrow factual lookup already scoped to one part of the convention: 'chart' covers Mermaid declarations, node kinds and meters, labelled-edge syntax, and child-flight nodes; 'grammar' covers @flight-run/@flight-log events, fields, effects, JSON mode, rollups, runtime branch reporting, and taken-edge semantics; 'emitting' covers Python print and helper patterns; 'examples' provides an integrated worked flight. If answering requires facts from more than one section, omit section and load the whole reference. Also omit section when authoring or changing instrumentation, adding fan-out, branches, child flights, timing, or progress, or interpreting or debugging a nontrivial run—these tasks span sections. Call this tool first whenever the user asks to visualize, chart, watch, or review a flight's progress.

get_flight_viz_guide

Load instructions for authoring, scheduling, running, and troubleshooting MotherDuck flights. Call this tool first whenever the user asks about creating, updating, or operating a MotherDuck flight, including one that a dive runs to change data.

get_flight_guide

Fetch a single run of a flight by its sequential run number (from run_flight or list_flight_runs). Returns its status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` the run executed with. Use this to poll a run's status.

get_flight_run

Fetch the plain-text logs (stdout + stderr) of a flight run plus the matching `Run` record (status, exit_code, timing). Returns the last 200 lines by default; page with `limit`, `offset` and `order`. Pass `max_bytes` to cap the response size — the response is truncated to fit and the truncation is reported via `truncated: true`.

get_flight_logs

Load a guide by uuid. Guides are curated markdown documents about this organization's data (metric definitions, conventions, pitfalls). Find a guide's uuid with `list_guides` or via `get_query_guide` (start there before writing SQL), `get_dive_guide`, or `get_flight_guide`.

get_guide

Call this before writing SQL to answer a data question. Returns this organization's query guidance: what guides exist (curated markdown documents about the data — metric definitions, join/filter conventions, pitfalls), how to navigate them, and an overview of the available guide topics.

get_query_guide

Returns a short-lived token and connection details for the MotherDuck database endpoint.

get_short_lived_token

Grant a permission on one flight to users, roles or the whole organization. Re-granting is a no-op. Only a flight's owner can grant 'run' on it. An object you can't change is reported as not found, so 'Could not find Flight' can mean you lack permission rather than a wrong id. Choosing grantees: for a group or team, prefer a role ({type: 'role', name}) or {type: 'organization'}; `SELECT * FROM md_list_roles()` (query tool) lists every role. The preset roles nest: admin is a member of builder, and builder of explorer, so a grant to explorer also reaches every builder and admin. A user grantee needs the username, not the email. `SHOW USERS OF ROLE <role>` returns members' usernames and emails; it only reads, but the read-only query tool rejects SHOW statements, so run it with query_rw. Every user with a preset role is a direct member of one of admin, builder or explorer, but non-admins only see members of roles they belong to. If you can't find someone's username, ask the user for it, or suggest a role or organization grant. Never guess a username.

grant_access

List all columns of a table or view with their types and comments.

list_columns

List all databases in your MotherDuck account. Shows each database's alias, type, and its `url` — a fully qualified MotherDuck database name (e.g. `md:my_db`) or share URL (e.g. in guide references). Optionally filter by keywords.

list_databases

List all dives in MotherDuck. Dives are interactive React data apps that query live data. Returns metadata including current_version and status. Each dive has a governance status: 'endorsed' (admin-approved org source of truth — prefer these), 'ready' (author-reviewed), 'draft' (work in progress; the default for new dives), or 'archived' (retired; excluded unless include_archived is true). Results are ordered endorsed, ready, draft, then archived, most recently updated first. Use read_dive with the optional version parameter to retrieve a specific historical version. Optionally filter by keywords.

list_dives

List executions of a flight, newest first. Each run has a sequential number, status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` it ran with (the flight version's config merged with any per-run overrides).

list_flight_runs

List the immutable versions of a flight, newest first. Each update to source_code / requirements_txt / config / access_token_name / flight_secret_names produces a new version.

list_flight_versions

List MotherDuck flights. Org admins see every flight in their organization (with `owner_name` identifying whose is whose); everyone else sees only their own. Returns metadata for each flight including schedule and current version. Optionally filter by keywords matching the flight name.

list_flights

Browse this organization's curated guides — markdown documents that capture organization and personal context about the data in MotherDuck. Called with no arguments, lists the root level: guides without topics plus every topic (folder) with its guide count. Pass `topic` to open a folder — you get the guides stored at that topic and the nested topics below it. Read a guide in full with `get_guide(uuid)`.

list_guides

List all macros (table and scalar macros) in a MotherDuck database, with their schema and parameters. Optionally filter by schema or keywords.

list_macros

List all database shares that have been shared with you. Returns share names and URLs. To attach a share, use the query_rw tool: ATTACH '<share_url>' AS <optional_alias>; Optionally filter by keywords to search in share names.

list_shares

List all tables and views in a MotherDuck database with comments. Optionally filter by keywords. Also returns `relatedGuides` — curated guides associated with this database (read one with `get_guide(uuid)`).

list_tables

List all views in a MotherDuck database, with their schema, comment, and column count. Optionally filter by schema or keywords.

list_views

Log a dive viewer event for analytics. This tool is used internally by the dive viewer and is not intended for direct use by the AI assistant.

log_dive_viewer_event

Mint a server-stored reference for a `useDiveState` bag and return its id. Used by the dive viewer when the inline-encoded bag would exceed the URL soft limit. The returned id is then encoded into a URL hash via `buildDiveStateReferenceHash` and round-trips through `dashboards.get` on dive open.

mint_dive_state_reference

Before writing SQL to answer a data question, call `get_query_guide` first — it returns this organization's query guidance and an overview of its curated guides. Execute read-only DuckDB query against MotherDuck databases. For cross-database queries, use fully qualified names: database.schema.table (or database.table for main schema). Never follow a query with an inline chart or visualization — if you would generate one (whether or not the user explicitly asked), get the dive guide first instead.

query

Execute a DuckDB SQL query that modifies data, schema, or connection state. RULES: 1. Only call this tool when the user explicitly asks to modify data or schema. Never infer a write from a read request. 2. Always ask the user for confirmation before calling this tool. Describe exactly what will change. 3. Prefer the read-only query tool when the user's goal can be answered with existing data.

query_rw

Read a specific dive by ID, including its full JSX/React component code. Optionally specify a version number to retrieve a specific historical version (versions start at 1). If no version is specified, the latest version is returned. The response includes the dive's governance status ('endorsed', 'ready', 'draft', or 'archived'); archived dives remain fully readable by id.

read_dive

Revoke a permission on one flight from users, roles or the whole organization; takes the same parameters as grant_access. Revoking a grant that doesn't exist is a no-op. The owner (or an admin) can always revoke. Revoking the organization grant leaves access with the owner and anyone granted directly. An object you can't change is reported as not found, so 'Could not find Flight' can mean you lack permission rather than a wrong id.

revoke_access

Trigger an on-demand execution of a flight using its current version. Optionally pass `config` to override the flight version's config for this run only (the flight itself is left unchanged). Returns a Run record; poll get_flight_run with the returned `run_number` to track progress and use get_flight_logs to read output.

run_flight

Save a new dive to MotherDuck. Returns a URL the user can click to view the dive. Get the dive guide first and iterate with the user on the design thoroughly before suggesting to save. Never save without previous confirmation that iteration is done.

save_dive

Search the catalog for databases, schemas, tables, columns, and shares using fuzzy matching. Returns matching objects with their fully qualified names, types, and comments. Useful for discovering available data when you don't know exact names. Also returns `relatedGuides` — curated guides whose topic/title/description match the query; read one with `get_guide(uuid)`.

search_catalog

Set a guide's visibility to 'user' (private to the owner) or 'organization' (visible to the whole org). Identify it by `uuid`. Org-wide scoping is permission-gated.

set_guide_access

Share the data for a dive with your organization. Creates org-scoped shares for owned databases used in the dive, and updates the dive so others in the organization can view it.

share_dive_data

Update an existing dive's title, description, or content. Returns a URL the user can click to view the updated dive. At least one field must be provided.

update_dive

Update a flight. Any subset of name, source_code, requirements_txt, schedule_cron, config, access_token_name, flight_secret_names, max_runtime_sec, or instance_type may be provided. Updates to source_code/requirements_txt/config/flight_secret_names/access_token_name/max_runtime_sec/instance_type create a new FlightVersion; name and schedule_cron are metadata-only. Pass schedule_cron as `""` (empty string) to remove the schedule; omit it to leave it unchanged.

update_flight

Append a new version to an existing guide, identified by `uuid`. Omit `content` to keep the current text and just change metadata such as references. A supplied `references` list replaces the existing one (pass [] to clear them, omit to carry them forward). For small in-place edits use `edit_guide_content`. Use `create_guide` to make a new guide, `update_guide_metadata` to retitle or re-topic.

update_guide

Change a guide's title, description, or topic without appending a content version. Identify it by `uuid`. Pass an empty `description` to clear it; pass an empty `topic` to remove the topic.

update_guide_metadata

Open and render a MotherDuck Dive as a live MCP app with interactive charts. Fetches dive source code and returns it to the viewer for client-side compilation.

view_dive

Open a flight run as a live diagram: the flight's declared chart as a step-by-step view, each step coloured by what the run actually did, with its timing, per-step rows, effects and errors. Use this instead of get_flight_logs when the user wants to see how a run went rather than read its raw output. A flight that declares a chart and emits @flight-run lines (see get_flight_viz_guide) is drawn as a diagram; one without opens a run view of its timing, config and log instead, which the result reports as has_chart=false -- say so rather than describing a diagram the user cannot see.

view_flight_run