# Dives

> Create, read, update, share, and render Dives — interactive data visualizations — through the MotherDuck MCP server.

## Included pages

- [get_dive_guide](https://motherduck.com/docs/sql-reference/mcp/dives/get-dive-guide): Load instructions for creating MotherDuck Dives
- [list_dives](https://motherduck.com/docs/sql-reference/mcp/dives/list-dives): List all Dives in your MotherDuck workspace
- [read_dive](https://motherduck.com/docs/sql-reference/mcp/dives/read-dive): Read a specific Dive by ID, including its full component code
- [view_dive](https://motherduck.com/docs/sql-reference/mcp/dives/view-dive): Render a MotherDuck Dive as a live, interactive MCP app inside the host client.
- [save_dive](https://motherduck.com/docs/sql-reference/mcp/dives/save-dive): Save a new Dive to your MotherDuck workspace
- [update_dive](https://motherduck.com/docs/sql-reference/mcp/dives/update-dive): Update an existing Dive's title, description, or content
- [share_dive_data](https://motherduck.com/docs/sql-reference/mcp/dives/share-dive-data): Share the data for a Dive with your organization
- [delete_dive](https://motherduck.com/docs/sql-reference/mcp/dives/delete-dive): Permanently delete a Dive by ID

Source: https://motherduck.com/docs/category/dives

---

## get_dive_guide

Source: https://motherduck.com/docs/sql-reference/mcp/dives/get-dive-guide

> Load instructions for creating MotherDuck Dives

Load instructions for creating MotherDuck [Dives](/docs/key-tasks/ai-and-motherduck/dives). Call this before creating or saving dives.

## Description

The `get_dive_guide` tool returns comprehensive instructions on how to write MotherDuck Dives—interactive React data apps that query live MotherDuck data. It provides guidance on the [`useSQLQuery` hook](/sql-reference/motherduck-sql-reference/dives/use-sql-query), data type conversions, available libraries, and design system. The guide content is tailored to the AI client you are using.

Call this tool before using [`save_dive`](../save-dive) or [`update_dive`](../update-dive) to ensure the generated code follows the correct format.

:::note
Dives are available on all MotherDuck plans at no additional charge.
:::

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client` | string | Yes | The AI client being used: `"claude"`, `"chatgpt"`, `"claude_code"`, or `"other"` |

### Client options

| Client | Use case |
|--------|----------|
| `claude` | Claude (Anthropic) through Claude.ai or API |
| `chatgpt` | ChatGPT (OpenAI) |
| `claude_code` | Claude Code (terminal-based agent) |
| `other` | Any other AI client or custom integration |

## Output schema

```json
{
  "success": boolean,
  "guide": string,              // Dive guide content (on success) or upgrade message
  "client": string,             // The client that was used (on success)
  "reason": string,             // "upgrade_required" (when plan doesn't support Dives)
  "plan": string,               // Current plan name (when upgrade required)
  "error": string               // Error message (on failure)
}
```

On success, `guide` contains the client-specific instructions for building Dives.

## Example usage

**Build a new Dive from Claude:**

```text
Create a Dive showing monthly revenue trends for my sales database
```

The AI assistant will first call `get_dive_guide` to load the instructions:

```json
{
  "client": "claude"
}
```

**Build a Dive from ChatGPT:**

```text
Create a Dive with a bar chart of customer signups by region
```

```json
{
  "client": "chatgpt"
}
```

**Build a Dive from Claude Code:**

```text
Create a Dive showing daily active users over the past 90 days
```

```json
{
  "client": "claude_code"
}
```

---

## list_dives

Source: https://motherduck.com/docs/sql-reference/mcp/dives/list-dives

> List all Dives in your MotherDuck workspace

List all owned [Dives](/docs/key-tasks/ai-and-motherduck/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](/docs/key-tasks/ai-and-motherduck/dives/dive-statuses) 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`](../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

```json
{
  "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:**

```text
What Dives do I have in my workspace?
```

The AI assistant will call the tool with no parameters.

**Filter Dives by keywords:**

```text
Show me my revenue-related Dives
```

The AI assistant will call the tool with keywords:

```json
{
  "keywords": "revenue"
}
```

**Include Archived Dives:**

```text
List all my Dives, including archived ones
```

The AI assistant will call the tool with:

```json
{
  "include_archived": true
}
```

**Find a specific Dive to update:**

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

## Success response example

```json
{
  "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
}
```

---

## read_dive

Source: https://motherduck.com/docs/sql-reference/mcp/dives/read-dive

> Read a specific Dive by ID, including its full component code

Read a specific [Dive](/docs/key-tasks/ai-and-motherduck/dives) 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.

## Description

The `read_dive` tool retrieves a Dive's complete details, including its title, description, [status](/docs/key-tasks/ai-and-motherduck/dives/dive-statuses), timestamps, and the full React component source code. Use this to inspect an existing Dive before updating it, or to understand how a Dive is built. Archived Dives are always readable by ID, even though they're excluded from [`list_dives`](../list-dives) by default.

Use [`list_dives`](../list-dives) first to find the Dive ID and its `current_version`.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the Dive to read |
| `version` | number | No | Version number to retrieve (1-indexed). Defaults to the latest version. |

## Output schema

```json
{
  "success": boolean,
  "dive": {                      // Dive object (on success)
    "id": string,                // Unique identifier (UUID)
    "title": string,             // Dive title
    "description": string,       // Dive description
    "content": string,           // Full JSX/React component code
    "current_version": number,   // Current version number
    "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
  },
  "error": string                // Error message (on failure)
}
```

## Example usage

**Read a Dive to inspect its code:**

```text
Show me the code for my revenue trends Dive
```

The AI assistant will call the tool with the Dive's ID:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

**Read a specific version of a Dive:**

```text
Show me version 1 of my revenue trends Dive
```

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1
}
```

**Read a Dive before updating it:**

```text
I want to modify my customer signups Dive—can you show me what it looks like?
```

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Monthly Revenue Trends",
    "description": "Line chart showing revenue by month",
    "content": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\n\nexport default function Dive() {\n  const { data, isLoading } = useSQLQuery(`SELECT ...`);\n  // ...\n}",
    "current_version": 3,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-20T14:45:00Z"
  }
}
```

## Error response example

```json
{
  "success": false,
  "error": "Dive with ID 'invalid-uuid' not found"
}
```

---

## view_dive

Source: https://motherduck.com/docs/sql-reference/mcp/dives/view-dive

> Render a MotherDuck Dive as a live, interactive MCP app inside the host client.

Render a [Dive](/key-tasks/ai-and-motherduck/dives) as an interactive MCP app inside hosts that support the dive viewer. The tool fetches the Dive's source code and metadata from MotherDuck; the host's dive viewer compiles and renders it client-side.

## Description

The `view_dive` tool opens a Dive in the host's MCP dive viewer, where the agent and the user can interact with live data. Optional inputs let you preview the same Dive against different databases or with a specific starting UI state without re-saving the Dive.

The tool also returns `dive_app_url` — a chat-side link the agent can offer to open the same Dive in `app.motherduck.com`. When `initial_state` is supplied, it rides along in the URL so the linked-to Dive opens at the same configured view as the inline preview.

Use [`list_dives`](../list-dives) to find a Dive's ID before calling `view_dive`.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dive_id` | string (UUID) | Yes | The unique identifier of the Dive to render. |
| `required_resources` | array of `{ url, alias? }` | No | Override the Dive's source-declared `REQUIRED_DATABASES` for this preview. |
| `initial_state` | object | No | Seed the Dive's initial UI state for this preview. Keys match those used by the `useDiveState` hook inside the Dive's code. Values must be JSON-serializable. |

### `required_resources` shape

```json
[
  {
    "url": "md:_share/<database>/<share_uuid>",
    "alias": "<local_alias>"
  }
]
```

`url` accepts a share URL (`md:_share/<database>/<share_uuid>`) or an owned database identifier (`md:<database_name>`). `alias` defaults to the database name from the URL when omitted.

When supplied, `required_resources` **replaces** the Dive's source-declared `REQUIRED_DATABASES` for the preview. Use it when the user wants to render a Dive against a specific share or embed configuration. For a permanent change to the Dive's target databases, edit the source and use [`update_dive`](../update-dive) instead.

### `initial_state` shape

```json
{
  "<state_key>": <json_value>,
  "<another_key>": <json_value>
}
```

Each key matches a `useDiveState(key, ...)` call inside the Dive's source. Interactive changes during the preview do not round-trip back to the MCP host; pass another `initial_state` on the next call if you want to start from the new state. Do not use `initial_state` for ephemeral UI state (input drafts, dialog open/close) — those use plain `useState` inside the Dive.

## Output schema

```json
{
  "success": boolean,
  "dive_id": string,             // UUID of the rendered Dive
  "title": string,               // Dive title
  "source": string,              // Full JSX/React component source
  "current_version": number,     // Latest version number for the Dive
  "dive_app_url": string,        // Chat-side link to open the Dive in app.motherduck.com
  "initial_state": object,       // Echoed back when supplied in the request
  "required_resources": array,   // Echoed back when supplied in the request
  "error": string                // Error message (on failure)
}
```

When `initial_state` is supplied, `dive_app_url` carries it in the URL fragment, so clicking the link opens the Dive at the same starting view as the inline preview. `required_resources` is **not** carried in `dive_app_url`: clicking the link opens the Dive against its source-declared `REQUIRED_DATABASES`, not the override. Use the [embed session API](/key-tasks/ai-and-motherduck/dives/embedding-dives/#override-required-databases) if you need the override to survive into the linked-to Dive.

## Example usage

**Open a Dive in the host's dive viewer:**

```text
Open my revenue trends Dive
```

The agent calls the tool with the Dive's ID:

```json
{
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

**Preview a Dive against a specific database:**

```text
Show me the customer analytics Dive against the staging share
```

```json
{
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "required_resources": [
    {
      "url": "md:_share/staging_data/9f4a2b8c-1234-5678-90ab-cdef01234567",
      "alias": "customer_analytics"
    }
  ]
}
```

**Preview a Dive in a specific UI state:**

```text
Show me the sales overview Dive filtered to EMEA, last quarter
```

```json
{
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "initial_state": {
    "region": "emea",
    "dateRange": { "start": "2026-01-01", "end": "2026-03-31" }
  }
}
```

## Success response example

```json
{
  "success": true,
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Monthly Revenue Trends",
  "source": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\n\nexport default function Dive() {\n  // ...\n}",
  "current_version": 3,
  "dive_app_url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890/monthly-revenue-trends#state=eyJyZWdpb24iOiJlbWVhIn0",
  "initial_state": {
    "region": "emea"
  }
}
```

## Error response example

```json
{
  "success": false,
  "error": "Dive 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found"
}
```

## Data exports from the dive viewer

The MCP dive viewer supports data export through the Dive's [`exportAs`](/sql-reference/motherduck-sql-reference/dives/use-sql-query/#export-query-results) buttons. When a user starts an export, the dive viewer generates the file (CSV, Parquet, or XLSX) from the browser DuckDB connection:

- **Hosts that support file downloads** receive the completed file directly through the MCP `downloadFile` capability.
- **Hosts that do not support `downloadFile`** show a fallback dialog with a link back to the Dive in MotherDuck so the user can export there.

Exports do not require any additional `view_dive` parameters; they're enabled by the Dive's source code.

## Related resources

- [Creating visualizations with Dives](/key-tasks/ai-and-motherduck/dives/)
- [Embedding Dives in your web application](/key-tasks/ai-and-motherduck/dives/embedding-dives/) — the embed-session equivalents of `required_resources` and `initial_state`

---

## save_dive

Source: https://motherduck.com/docs/sql-reference/mcp/dives/save-dive

> Save a new Dive to your MotherDuck workspace

Save a new [Dive](/docs/key-tasks/ai-and-motherduck/dives) to MotherDuck. Returns a URL to the Dive in MotherDuck as a link that the user can click to view the Dive.

## Description

The `save_dive` tool creates a new Dive in your MotherDuck workspace. It accepts a title, optional description, and the JSX/React component code. Before saving, the tool validates the code to check for common issues like invalid SQL queries or missing exports.

After saving, the tool analyzes which databases the Dive queries. If any referenced databases are not yet shared with your organization, it prompts you to use [`share_dive_data`](../share-dive-data) so others in your organization can view the Dive.

Call [`get_dive_guide`](../get-dive-guide) first to learn the required JSX/React format.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | The title of the Dive |
| `description` | string | No | A brief description of the Dive |
| `content` | string | Yes | The JSX/React component code for the Dive |

## Output schema

```json
{
  "success": boolean,
  "dive": {                        // Created dive info (on success)
    "id": string,                  // Unique identifier (UUID)
    "title": string,               // Dive title
    "description": string | null   // Dive description
  },
  "dive_url": string,              // URL to view the Dive (on success)
  "warnings": string[],            // Validation warnings (if any)
  "database_warnings": string[],   // Warnings from database analysis (if any)
  "unshared_databases": string[],  // Database names not yet shared with the org (if any)
  "next_steps": string[],          // Ordered instructions for the AI to follow after saving
  "error": string,                 // Error message (on failure)
  "validationErrors": [            // Validation errors (on failure)
    {
      "type": string,              // Error type
      "message": string,           // Error description
      "details": string            // Additional details
    }
  ]
}
```

## Example usage

**Create a new Dive:**

```text
Create a Dive showing monthly revenue trends for my analytics database
```

The AI assistant will first call [`get_dive_guide`](../get-dive-guide) to load the instructions, then call `save_dive`:

```json
{
  "title": "Monthly Revenue Trends",
  "description": "Line chart showing revenue by month with year-over-year comparison",
  "content": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\nimport { LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer } from \"recharts\";\n\nexport default function Dive() {\n  const { data, isLoading, isError, error } = useSQLQuery(`\n    SELECT DATE_TRUNC('month', order_date) as month, SUM(revenue) as revenue\n    FROM analytics.sales\n    GROUP BY 1 ORDER BY 1\n  `);\n  // ... component code\n}"
}
```

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Monthly Revenue Trends",
    "description": "Line chart showing revenue by month with year-over-year comparison"
  },
  "dive_url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "unshared_databases": ["analytics"],
  "next_steps": [
    "Regenerate the dive preview artifact with the updated banner...",
    "Show the dive to the user in chat as a markdown hyperlink: [Monthly Revenue Trends](https://app.motherduck.com/dives/a1b2c3d4-...)",
    "The dive references databases not yet shared with the organization: analytics. Ask the user if they want to share them."
  ]
}
```

## Validation error response example

```json
{
  "success": false,
  "error": "Dive validation failed",
  "validationErrors": [
    {
      "type": "SQL_ERROR",
      "message": "Query validation failed: Table 'analytics.nonexistent_table' not found",
      "details": "SELECT * FROM analytics.nonexistent_table"
    }
  ],
  "hint": "Please fix the errors above and try again."
}
```

---

## update_dive

Source: https://motherduck.com/docs/sql-reference/mcp/dives/update-dive

> Update an existing Dive's title, description, or content

Update an existing [Dive's](/docs/key-tasks/ai-and-motherduck/dives) title, description, or content. Returns a URL to the Dive in MotherDuck as a link the user can click to view the updated Dive.

## Description

The `update_dive` tool modifies an existing Dive in your MotherDuck workspace. You can update the title, description, content (React component code), or any combination. At least one field must be provided.

When updating content, the tool validates the new code before saving, just like [`save_dive`](../save-dive). It also analyzes which databases the Dive queries and reports any unshared databases.

Use [`list_dives`](../list-dives) to find the Dive ID, and [`read_dive`](../read-dive) to inspect the current code before modifying it.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the Dive to update |
| `title` | string | No | New title for the Dive |
| `description` | string | No | New description for the Dive |
| `content` | string | No | New JSX/React component code |

At least one of `title`, `description`, or `content` must be provided.

## Output schema

```json
{
  "success": boolean,
  "dive": {                        // Updated dive info (on success)
    "id": string                   // Dive identifier
  },
  "dive_url": string,              // URL to view the Dive (on success)
  "warnings": string[],            // Validation warnings (if any)
  "database_warnings": string[],   // Warnings from database analysis (if any)
  "unshared_databases": string[],  // Database names not yet shared with the org (if any)
  "next_steps": string[],          // Ordered instructions for the AI to follow after updating
  "error": string,                 // Error message (on failure)
  "validationErrors": [            // Validation errors (on failure)
    {
      "type": string,
      "message": string,
      "details": string
    }
  ]
}
```

## Example usage

**Update a Dive's content:**

```text
Add a region filter to my revenue trends Dive
```

The AI assistant will call `read_dive` to get the current code, modify it, then call `update_dive`:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\n// ... updated component with region filter\n"
}
```

**Update just the title and description:**

```text
Rename my revenue Dive to "Q1 Revenue Dashboard"
```

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Q1 Revenue Dashboard",
  "description": "Revenue trends filtered to Q1 2025"
}
```

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "dive_url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "next_steps": [
    "Regenerate the dive preview artifact with the updated banner...",
    "Show the dive to the user in chat as a markdown hyperlink using the dive title: [dive title](https://app.motherduck.com/dives/a1b2c3d4-...)"
  ]
}
```

## Error response example

```json
{
  "success": false,
  "error": "At least one of title, description, or content must be provided"
}
```

---

## share_dive_data

Source: https://motherduck.com/docs/sql-reference/mcp/dives/share-dive-data

> Share the data for a Dive with your organization

Share the data for a [Dive](/docs/key-tasks/ai-and-motherduck/dives) with your organization. Creates org-scoped shares for owned databases used in the Dive, so others in the organization can view it.

## Description

The `share_dive_data` tool makes a Dive's underlying data accessible to your organization. When a Dive queries databases that you own but haven't shared, other users in your organization won't be able to view the Dive. This tool creates shares for those databases and updates the Dive to reference the shared versions.

The tool:

1. Verifies you own the Dive
2. Analyzes the Dive's SQL queries to find referenced databases
3. Creates org-scoped shares for any databases that aren't already shared
4. Updates the Dive to use the shared database references

Use this after [`save_dive`](../save-dive) or [`update_dive`](../update-dive) when you want your team to be able to view a Dive that queries your private databases.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `diveId` | string | Yes | The unique identifier (UUID) of the Dive to share data for |

## Output schema

```json
{
  "success": boolean,
  "dive": {                      // Dive info (on success)
    "id": string,                // Dive identifier
    "title": string,             // Dive title
    "version": number            // New version number after update
  },
  "shares": [                    // Shares created (on success)
    {
      "database": string,        // Database name
      "shareName": string,       // Share name
      "shareUrl": string,        // Share URL for the database
      "created": boolean         // Whether the share was newly created
    }
  ],
  "requiredDatabases": [         // All databases referenced by the Dive
    {
      "type": string,            // "share" or "database"
      "path": string,            // Share URL or database path
      "alias": string            // Database alias name
    }
  ],
  "url": string,                 // URL to view the Dive (on success)
  "message": string,             // Status message (on success)
  "warnings": string[],          // Warnings from analysis or sharing (if any)
  "error": string                // Error message (on failure)
}
```

## Example usage

**Share a Dive's data after saving:**

```text
Share the data for my revenue Dive with the rest of my team
```

The AI assistant will call the tool with the Dive's ID:

```json
{
  "diveId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

**Respond to a sharing prompt after save:**

After calling [`save_dive`](../save-dive), the tool may suggest sharing unshared databases. The AI assistant will call `share_dive_data` to make the data accessible:

```json
{
  "diveId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Monthly Revenue Trends",
    "version": 4
  },
  "shares": [
    {
      "database": "analytics",
      "shareName": "analytics",
      "shareUrl": "md:_share/analytics/a1b2c3d4-...",
      "created": true
    }
  ],
  "requiredDatabases": [
    {
      "type": "share",
      "path": "md:_share/analytics/a1b2c3d4-...",
      "alias": "analytics"
    }
  ],
  "url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Created 1 share(s). Dive updated with share URLs."
}
```

## Nothing to share response example

When all referenced databases are already shared:

```json
{
  "success": true,
  "message": "All referenced databases are already shared. No action needed.",
  "shares": [],
  "requiredDatabases": [
    {
      "type": "share",
      "path": "md:_share/analytics/a1b2c3d4-...",
      "alias": "analytics"
    }
  ],
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "version": 3
  }
}
```

## Error response example

```json
{
  "success": false,
  "error": "You don't own this dive or it doesn't exist"
}
```

---

## delete_dive

Source: https://motherduck.com/docs/sql-reference/mcp/dives/delete-dive

> Permanently delete a Dive by ID

Delete a [Dive](/docs/key-tasks/ai-and-motherduck/dives) by ID. This action is permanent and cannot be undone.

## Description

The `delete_dive` tool permanently removes a Dive from your MotherDuck workspace. Once deleted, the Dive cannot be recovered.

Use [`list_dives`](../list-dives) to find the Dive ID before deleting.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the Dive to delete |

## Output schema

```json
{
  "success": boolean,
  "message": string,             // Status message (on success)
  "error": string                // Error message (on failure)
}
```

## Example usage

**Delete a Dive:**

```text
Delete the old revenue Dive I no longer need
```

The AI assistant will call `list_dives` to find the Dive, confirm with the user, then call `delete_dive`:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## Success response example

```json
{
  "success": true,
  "message": "Dive 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' deleted successfully."
}
```

## Error response example

```json
{
  "success": false,
  "error": "Dive with id 'invalid-uuid' not found"
}
```

---