list_columns

List all columns of a table or view with their types and comments.

Description

The list_columns tool returns detailed column information for a specified table or view, including data types, nullability, and any comments. This is useful for understanding table structure before writing queries.

Input Parameters

Parameter	Type	Required	Description
table	string	Yes	Table or view name
database	string	Yes	Database name
schema	string	No	Schema name (defaults to main)

Output Schema

{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema name
  "table": string,               // Table or view name
  "objectType": "table" | "view", // Whether it's a table or view
  "columns": [                   // List of columns (on success)
    {
      "name": string,            // Column name
      "type": string,            // Data type
      "nullable": boolean,       // Whether nulls are allowed
      "comment": string | null   // Column comment if set
    }
  ],
  "columnCount": number,         // Number of columns
  "error": string                // Error message (on failure)
}

Example Usage

Get columns for a table:

What columns does the customers table have in my_database?

The AI assistant will call the tool with:

{
  "table": "customers",
  "database": "my_database"
}

Get columns in a specific schema:

Show me the schema of staging.raw_events in analytics_db

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

Success Response Example

{
  "success": true,
  "database": "my_database",
  "schema": "main",
  "table": "customers",
  "objectType": "table",
  "columns": [
    {
      "name": "id",
      "type": "INTEGER",
      "nullable": false,
      "comment": "Primary key"
    },
    {
      "name": "email",
      "type": "VARCHAR",
      "nullable": false,
      "comment": "Customer email address"
    },
    {
      "name": "name",
      "type": "VARCHAR",
      "nullable": true,
      "comment": "Full name"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "nullable": false,
      "comment": null
    },
    {
      "name": "metadata",
      "type": "JSON",
      "nullable": true,
      "comment": "Additional customer attributes"
    }
  ],
  "columnCount": 5
}

Error Response Example

{
  "success": false,
  "error": "Catalog Error: Table \"nonexistent_table\" does not exist"
}