MotherDuck

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.

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.

Delete a dive by ID. This action is permanent and cannot be undone.

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.

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.

Edit a dive's content by applying one or more text replacements, then save to MotherDuck. Accepts `id` (dive UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current content from MotherDuck, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior read_dive call is needed.

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.

Create a new MotherDuck flight. Read the flight guide before you create your first flight. A flight is a Python entrypoint (`source_code`) plus an optional `requirements_txt` that runs on MotherDuck compute. Optionally provide an `access_token_name` so the flight can connect to MotherDuck at runtime; omit it to use the default MotherDuck Flights access token. Optionally provide a 5-field cron expression to run on a schedule, and an optional `max_runtime_sec` to cap how long a run may take. Use flights for ELT/ETL pipelines, loading external data into MotherDuck, refreshing materialized views, or any recurring Python job that reads/writes MotherDuck data.

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.

List MotherDuck flights you own. Returns metadata for each flight including schedule and current version. Optionally filter by keywords matching the flight name.

Update a flight. Any subset of name, source_code, requirements_txt, schedule_cron, config, access_token_name, flight_secret_names, or max_runtime_sec may be provided. Updates to source_code/requirements_txt/config/flight_secret_names/access_token_name/max_runtime_sec 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.

Edit a flight's source_code by applying one or more text replacements, then save as a new FlightVersion. Accepts `id` (flight UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current source_code, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_flight call is needed.

Permanently delete a flight, its versions, schedule, and run history. This action cannot be undone.

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.

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 list_flight_runs to track progress and use get_flight_logs to read output.

Cancel an in-flight run of a flight. Identified by the flight UUID and the sequential run number (from list_flight_runs). Returns `canceled: true` on a successful transition; calling on an already-terminal run or one that doesn't exist returns a tool error.

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

Fetch the plain-text logs (stdout + stderr) of a flight run plus the matching `Run` record (status, exit_code, timing). Logs may be large; pass `max_bytes` to cap the response size — the response will be the tail when truncated.

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

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.

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)`.

Create a new guide — a markdown document that agents read to answer this org's data questions correctly (metric definitions, join/filter conventions, pitfalls). Group related guides with a lowercase kebab-case `topic` (e.g. 'revenue-billing' or 'core/metrics'); omit it for a guide without a topic. Visibility is controlled by `access`: 'user' (private, default) or 'organization' (org-wide, permission-gated). Personal dive/flight style guides belong under topic 'dives' / 'flights' with access 'user'. Attach `references` to the 1–5 objects the guide is authoritative about.

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.

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.

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.

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.

Soft-delete a guide while preserving its version history. Identify it by `uuid`.

Execute a read-only DuckDB query on behalf of a dive. This tool is used by the dive viewer and is not intended for direct use by the AI assistant.

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.

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.

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

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.