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

# Tools and Resources

> Complete reference for DynamoSQL MCP tools, resources, and prompts.

## Tools

Tools are the primary way AI assistants interact with your DynamoDB data. Each tool is only available when the bearer token includes the required scope.

Bearer tokens may come from either:

* interactive browser login (`authorization_code` + PKCE + consent + refresh token)
* API client credentials (`client_credentials`)

### list\_tables

Lists tables available in one schema for the authenticated tenant.

**Required scope:** `schemas:read`

**Arguments:**

| Name          | Type   | Required | Description                                                      |
| ------------- | ------ | -------- | ---------------------------------------------------------------- |
| `schema_name` | string | No       | Schema to list. Defaults to the tenant's default schema.         |
| `refresh`     | string | No       | Metadata refresh mode: `if_stale` (default), `force`, or `skip`. |

**Response fields:**

| Field                 | Description                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `schema_name`         | Resolved schema name                                                                                          |
| `tables`              | Array of table objects with `name`, `qualified_name`, `physical_table_name`, `item_count`, and `refreshed_at` |
| `truncated`           | `true` when more than 200 tables exist (results capped at 200)                                                |
| `refreshed`           | Whether metadata was refreshed on this call                                                                   |
| `refreshed_at`        | ISO timestamp of the last metadata refresh                                                                    |
| `stale_after_seconds` | Seconds until metadata is considered stale                                                                    |

**Example interaction:**

> **User:** "What tables do I have?"
>
> **Assistant calls:** `list_tables` with `{}`
>
> **Result:** 3 tables -- `orders`, `customers`, `products` in schema `east`

***

### describe\_table

Returns column, index, and type metadata for a single table.

**Required scope:** `schemas:read`

**Arguments:**

| Name          | Type   | Required | Description                                                           |
| ------------- | ------ | -------- | --------------------------------------------------------------------- |
| `table_name`  | string | Yes      | Table name to describe.                                               |
| `schema_name` | string | No       | Schema containing the table. Defaults to the tenant's default schema. |
| `refresh`     | string | No       | Metadata refresh mode: `if_stale` (default), `force`, or `skip`.      |

**Response fields:**

| Field                 | Description                                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `schema_name`         | Resolved schema name                                                                                       |
| `table_name`          | Resolved table name                                                                                        |
| `qualified_name`      | `schema_name.table_name`                                                                                   |
| `physical_table_name` | Physical DynamoDB table name used for execution                                                            |
| `item_count`          | Approximate row count                                                                                      |
| `refreshed`           | Whether metadata was refreshed on this call                                                                |
| `refreshed_at`        | ISO timestamp of the last metadata refresh for this table                                                  |
| `stale_after_seconds` | Seconds until metadata is considered stale                                                                 |
| `columns`             | Array of column objects with `name`, `type`, and `nullable`                                                |
| `indexes`             | Array of index objects with `name`, `type`, `hashKey`, `hashKeyType`, and optional `sortKey`/`sortKeyType` |
| `attribute_types`     | DynamoDB attribute type mappings                                                                           |

**Example interaction:**

> **User:** "What columns does the orders table have?"
>
> **Assistant calls:** `describe_table` with `{ "table_name": "orders" }`
>
> **Result:** Columns `order_id` (S, primary key), `customer_id` (S), `total` (N), `status` (S), `order_date` (S)

***

### run\_sql

Executes a read-only SQL query against the authenticated tenant's data.

**Required scope:** `query`

**Arguments:**

| Name       | Type    | Required | Description                                               |
| ---------- | ------- | -------- | --------------------------------------------------------- |
| `sql`      | string  | Yes      | SQL query to execute. Must begin with `SELECT` or `WITH`. |
| `max_rows` | integer | No       | Maximum rows to return (1--1000, default 100).            |

**Response fields:**

| Field         | Description                                           |
| ------------- | ----------------------------------------------------- |
| `columns`     | Array of column names                                 |
| `rows`        | Array of row objects                                  |
| `firstRowIdx` | Index of the first row in the result set              |
| `resumeIdx`   | Next row index for pagination (absent when exhausted) |
| `planTime`    | Parse and plan time in milliseconds                   |
| `execTime`    | Total execution time in milliseconds                  |

**Error cases:**

| Condition                                  | Behavior                                                             |
| ------------------------------------------ | -------------------------------------------------------------------- |
| SQL does not start with `SELECT` or `WITH` | Returns tool error: "Only read-only SELECT statements are supported" |
| SQL syntax error                           | Returns tool error with parse error details                          |
| Table not found                            | Returns tool error with table resolution failure                     |

**Example interaction:**

> **User:** "Show me the top 5 customers by total spend"
>
> **Assistant calls:** `run_sql` with:
>
> ```json theme={null}
> {
>   "sql": "SELECT customer_id, SUM(total) AS total_spend FROM east.orders GROUP BY customer_id ORDER BY total_spend DESC LIMIT 5",
>   "max_rows": 5
> }
> ```
>
> **Result:** 5 rows with `customer_id` and `total_spend` columns

***

## Resources

Resources provide static documentation that AI assistants can read for context about DynamoSQL's SQL capabilities.

### docs\://sql-overview

High-level summary of supported SQL features including SELECT, JOINs, CTEs, aggregations, subqueries, set operations, and functions. Includes an example query.

### docs\://sql-limitations

List of unsupported features including write operations, DDL, window functions, recursive CTEs, CAST/CONVERT, and behavioral notes about pagination and string escaping.

<Tip>
  AI assistants can read these resources to understand what SQL syntax is available before writing queries, reducing errors from unsupported features.
</Tip>

***

## Prompts

Prompts are guided workflows that help AI assistants follow best practices when exploring data or writing queries.

### explore-data

Guides the AI through schema discovery before querying.

**Arguments:**

| Name          | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `goal`        | string | No       | What the user wants to explore or learn about the data. |
| `schema_name` | string | No       | Preferred schema to start with.                         |

**Behavior:** Instructs the AI to call `list_tables` first, then `describe_table` on relevant tables, and keep queries bounded with `LIMIT`.

### write-query

Helps the AI write a read-only query that respects DynamoSQL limitations.

**Arguments:**

| Name          | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `request`     | string | Yes      | Natural language description of the desired query. |
| `schema_name` | string | No       | Schema to target.                                  |
| `table_name`  | string | No       | Preferred table.                                   |

**Behavior:** Instructs the AI to use only `SELECT` syntax, avoid unsupported features (INSERT, UPDATE, DELETE, DDL, window functions, CAST), and reference the SQL limitations documentation when needed.

***

## Metadata refresh modes

The `refresh` parameter on `list_tables` and `describe_table` controls how table metadata is loaded:

| Mode       | Behavior                                                                           |
| ---------- | ---------------------------------------------------------------------------------- |
| `if_stale` | Refreshes metadata only if older than the configured staleness threshold (default) |
| `force`    | Always refreshes metadata from DynamoDB, even if recently cached                   |
| `skip`     | Uses cached metadata without checking freshness                                    |

Use `force` when you know table structure has recently changed. Use `skip` to avoid refresh latency when metadata accuracy is not critical.

## Interactive registration notes

For browser-based login, the MCP server can recognize interactive clients through:

* exact pre-registration in DynamoSQL
* Client ID Metadata Documents (CIMD)
* Dynamic Client Registration (DCR) for public interactive clients

CIMD notes:

* `client_id` must be an HTTPS URL with a path
* DynamoSQL fetches the metadata document server-side
* the metadata document must allow `authorization_code`, `code`, and `token_endpoint_auth_method = none`

DCR notes:

* `POST /register` returns an opaque `client_id`
* DCR clients are public clients only in this release
* loopback HTTP redirect URIs are allowed only for `127.0.0.1` and `localhost`