Skip to main content

​
Overview

List all tables and views in a database with their schema, type, and comments. If the database parameter is not specified, the tool uses the current database. This tool helps discover available data structures before querying. Tables and views are queried using DuckDB’s system functions (duckdb_tables() and duckdb_views()) and returned in a structured format with metadata.

​
Parameters

​
database
string
Database name to list tables from. If not specified, defaults to the current database obtained via current_database().
​
schema
string
Optional schema name to filter results. If not specified, tables and views from all schemas are returned.

​
Response

​
success
boolean
required
Indicates whether the operation completed successfully.
​
database
string
required
The database that was queried.
​
schema
string
required
The schema filter applied. Returns “all” if no schema was specified.
​
tables
array
required
Array of table and view objects. Each object contains:
  • schema (string): Schema name containing the table/view
  • name (string): Table or view name
  • type (string): Either “table” or “view”
  • comment (string | null): User-defined comment, or null if not set
​
tableCount
integer
required
Number of tables in the results.
​
viewCount
integer
required
Number of views in the results.
​
error
string
Error message when success is false.
​
errorType
string
Type of error that occurred.

​
Examples

​
List Tables in Current Database

Request: 
{}
Response: 
{
  "success": true,
  "database": "main",
  "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": "products",
      "type": "table",
      "comment": null
    },
    {
      "schema": "main",
      "name": "active_customers",
      "type": "view",
      "comment": "View of customers with recent activity"
    }
  ],
  "tableCount": 3,
  "viewCount": 1
}

​
List Tables in Specific Database

Request: 
{
  "database": "analytics"
}
Response: 
{
  "success": true,
  "database": "analytics",
  "schema": "all",
  "tables": [
    {
      "schema": "main",
      "name": "daily_metrics",
      "type": "table",
      "comment": "Aggregated daily metrics"
    },
    {
      "schema": "main",
      "name": "user_cohorts",
      "type": "table",
      "comment": null
    },
    {
      "schema": "staging",
      "name": "raw_events",
      "type": "table",
      "comment": "Raw event data from ingestion"
    }
  ],
  "tableCount": 3,
  "viewCount": 0
}

​
List Tables in Specific Schema

Request: 
{
  "database": "analytics",
  "schema": "staging"
}
Response: 
{
  "success": true,
  "database": "analytics",
  "schema": "staging",
  "tables": [
    {
      "schema": "staging",
      "name": "raw_events",
      "type": "table",
      "comment": "Raw event data from ingestion"
    },
    {
      "schema": "staging",
      "name": "temp_imports",
      "type": "table",
      "comment": null
    }
  ],
  "tableCount": 2,
  "viewCount": 0
}

​
MotherDuck Database

Request: 
{
  "database": "my_db"
}
Response: 
{
  "success": true,
  "database": "my_db",
  "schema": "all",
  "tables": [
    {
      "schema": "main",
      "name": "sales_data",
      "type": "table",
      "comment": "Sales transactions from CRM"
    },
    {
      "schema": "main",
      "name": "customer_segments",
      "type": "view",
      "comment": "Customer segmentation analysis"
    }
  ],
  "tableCount": 1,
  "viewCount": 1
}

​
Empty Database

Request: 
{
  "database": "empty_db"
}
Response: 
{
  "success": true,
  "database": "empty_db",
  "schema": "all",
  "tables": [],
  "tableCount": 0,
  "viewCount": 0
}

​
Error Response

Request: 
{
  "database": "nonexistent_db"
}
Response: 
{
  "success": false,
  "error": "Catalog Error: Database with name nonexistent_db does not exist!",
  "errorType": "CatalogException"
}

​
Default Behavior

Current Database: When no database parameter is provided, the tool automatically uses current_database() to determine which database to query. This is typically “main” for local DuckDB files, or your default MotherDuck database.
All Schemas: When no schema parameter is provided, tables and views from all schemas are returned. Most databases use the “main” schema by default, but you may see tables in other schemas like “information_schema”, “pg_catalog”, or custom schemas.

​
Tool Annotations

This tool is always read-only with readOnlyHint: true and destructiveHint: false, regardless of server mode.

Build docs developers (and LLMs) love

Get started for freeTalk to us