> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auxilian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# describe_table

> Get the columns and foreign keys of one table.

Returns one table's definition. Call it before reading or writing rows so values match the column types.

| | |
| - | - |
| Scope | `mcp:read` |
| Annotations | `readOnlyHint: true` |

## Parameters

<ParamField body="projectId" type="string" required>
  Project id from `list_projects`.
</ParamField>

<ParamField body="table" type="string" required>
  Table name.
</ParamField>

## Result

<ResponseField name="table" type="string">
  Table name.
</ResponseField>

<ResponseField name="columns" type="object[]">
  Columns in table order. The first two are always the system columns `id` and `created_at`.

  <Expandable title="column">
    <ResponseField name="name" type="string">
      Column name.
    </ResponseField>

    <ResponseField name="type" type="string">
      One of `text`, `integer`, `numeric`, `boolean`, `timestamptz`, `uuid`, `jsonb`.
    </ResponseField>

    <ResponseField name="nullable" type="boolean">
      `false` when the column is `NOT NULL`. Omitted when the column is nullable.
    </ResponseField>

    <ResponseField name="default" type="string">
      `now()` or `gen_random_uuid()` when the column has a default. Omitted otherwise.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="foreignKeys" type="object[]">
  Foreign keys. Omitted when the table has none.

  <Expandable title="foreign key">
    <ResponseField name="column" type="string">
      The `uuid` column in this table.
    </ResponseField>

    <ResponseField name="refTable" type="string">
      The table it references.
    </ResponseField>

    <ResponseField name="refColumn" type="&#x22;id&#x22;">
      Always `id`.
    </ResponseField>

    <ResponseField name="onDelete" type="string">
      `cascade`, `restrict`, or `set null`. Omitted when none was given at creation, which behaves as `restrict`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

```json Arguments theme={null}
{ "projectId": "01k7m3x9q2v8d4h6n1r5t0w2yz", "table": "books" }
```

```json Result theme={null}
{
  "data": {
    "table": "books",
    "columns": [
      { "name": "id", "type": "uuid", "nullable": false, "default": "gen_random_uuid()" },
      { "name": "created_at", "type": "timestamptz", "nullable": false, "default": "now()" },
      { "name": "title", "type": "text", "nullable": false },
      { "name": "author_id", "type": "uuid" },
      { "name": "finished", "type": "boolean" },
      { "name": "rating", "type": "integer" },
      { "name": "details", "type": "jsonb" }
    ],
    "foreignKeys": [
      { "column": "author_id", "refTable": "authors", "refColumn": "id", "onDelete": "set null" }
    ]
  }
}
```

## Errors

| Code | When |
| - | - |
| `ACCESS_DENIED` | The project doesn't exist or you can't access it |
| `VALIDATION` | The table doesn't exist, or the name is invalid |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.