list_dives

Public Preview

Dives are currently in public preview and functionality is subject to change.

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) for each Dive. 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)

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
    }
  ],
  "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"
}

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"
    },
    {
      "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"
    }
  ],
  "count": 2,
  "totalCount": 2
}