list_dives

List all owned Dives in MotherDuck. Dives are interactive React data apps that query live data. Returns metadata including current_version (the latest version number, 1-indexed) and the status for each Dive. Results are ordered from most to least trusted status (Endorsed, Ready, Draft, then Archived), with the latest updates first, and Archived Dives are excluded unless requested. Use read_dive with the optional version parameter to retrieve a specific historical version. Optionally filter by keywords to search in title and description.

Description

The list_dives tool returns a list of all Dives in your MotherDuck workspace. Each Dive includes its ID, title, description, owner, version history, and timestamps. Use this to discover existing Dives before reading, updating, or deleting them.

Input parameters

Parameter	Type	Required	Description
keywords	string	No	Keywords to filter dives by title or description (case-insensitive, all words must match)
include_archived	boolean	No	Include Archived Dives in the results. Defaults to false. Archived Dives remain readable with read_dive.

Output schema

{
  "success": boolean,
  "dives": [                     // Array of dives (on success)
    {
      "id": string,              // Unique identifier (UUID)
      "title": string,           // Dive title
      "description": string,     // Dive description
      "owner_name": string,      // Name of the Dive owner
      "current_version": number, // Latest version number (1-indexed)
      "created_at": string,      // ISO 8601 creation timestamp
      "updated_at": string,      // ISO 8601 last update timestamp
      "status": string,          // "draft", "ready", "endorsed", or "archived"
      "status_changed_at": string,          // ISO 8601 timestamp; null until the status is set
      "status_applies_to_version": number   // Version the status was set against; null until set
    }
  ],
  "count": number,               // Number of dives returned
  "totalCount": number,          // Total number of matching dives
  "truncated": boolean,          // Whether the results were truncated
  "message": string,             // Truncation message (when truncated)
  "error": string                // Error message (on failure)
}

Example usage

List all Dives:

What Dives do I have in my workspace?

The AI assistant will call the tool with no parameters.

Filter Dives by keywords:

Show me my revenue-related Dives

The AI assistant will call the tool with keywords:

{
  "keywords": "revenue"
}

Include Archived Dives:

List all my Dives, including archived ones

The AI assistant will call the tool with:

{
  "include_archived": true
}

Find a specific Dive to update:

Show me my existing Dives so I can update the revenue dashboard

Success response example

{
  "success": true,
  "dives": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Monthly Revenue Trends",
      "description": "Line chart showing revenue by month with category breakdown",
      "owner_name": "alice",
      "current_version": 3,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:45:00Z",
      "status": "endorsed",
      "status_changed_at": "2025-01-21T08:00:00Z",
      "status_applies_to_version": 3
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "title": "Customer Signups by Region",
      "description": "Bar chart of customer signups grouped by region",
      "owner_name": "bob",
      "current_version": 1,
      "created_at": "2025-01-18T09:00:00Z",
      "updated_at": "2025-01-18T09:00:00Z",
      "status": "draft",
      "status_changed_at": null,
      "status_applies_to_version": null
    }
  ],
  "count": 2,
  "totalCount": 2
}