---
sidebar_position: 3
title: list_tables
description: List tables and views in a MotherDuck database
---

# 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

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

```text
Show me all tables in my_database
```

The AI assistant will call the tool with:

```json
{
  "database": "my_database"
}
```

**List tables in a specific schema:**

```text
What tables are in the staging schema of analytics_db?
```

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

## Success Response Example

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

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