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.
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. |
| 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 |
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. |
| 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 |
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). |
| 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 |
| 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 |
User: “Show me the top 5 customers by total spend”
Assistant calls: run_sql with:
{
"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
}
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.
AI assistants can read these resources to understand what SQL syntax is available before writing queries, reducing errors from unsupported features.
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. |
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. |
SELECT syntax, avoid unsupported features (INSERT, UPDATE, DELETE, DDL, window functions, CAST), and reference the SQL limitations documentation when needed.
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 |
force when you know table structure has recently changed. Use skip to avoid refresh latency when metadata accuracy is not critical. 
