list_tables

List all tables and views in a MotherDuck database with their comments.

Description

The list_tables tool returns all tables and views in a specified database, including their schema, type (table or view), and any comments that have been added. You can optionally filter by schema.

Input Parameters

Parameter	Type	Required	Description
database	string	Yes	Database name to list tables from
schema	string	No	Schema name to filter by (defaults to all schemas)

Output Schema

{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema filter used ("all" if not specified)
  "tables": [                    // List of tables and views (on success)
    {
      "schema": string,          // Schema name
      "name": string,            // Table or view name
      "type": "table" | "view",  // Object type
      "comment": string | null   // Table/view comment if set
    }
  ],
  "tableCount": number,          // Number of tables
  "viewCount": number,           // Number of views
  "error": string                // Error message (on failure)
}

Example Usage

List all tables in a database:

Show me all tables in my_database

The AI assistant will call the tool with:

{
  "database": "my_database"
}

List tables in a specific schema:

What tables are in the staging schema of analytics_db?

{
  "database": "analytics_db",
  "schema": "staging"
}

Success Response Example

{
  "success": true,
  "database": "my_database",
  "schema": "all",
  "tables": [
    {
      "schema": "main",
      "name": "customers",
      "type": "table",
      "comment": "Customer master data"
    },
    {
      "schema": "main",
      "name": "orders",
      "type": "table",
      "comment": "Order transactions"
    },
    {
      "schema": "main",
      "name": "monthly_sales",
      "type": "view",
      "comment": "Aggregated monthly sales view"
    },
    {
      "schema": "staging",
      "name": "raw_events",
      "type": "table",
      "comment": null
    }
  ],
  "tableCount": 3,
  "viewCount": 1
}

Error Response Example

{
  "success": false,
  "error": "Catalog Error: Database \"nonexistent_db\" does not exist"
}