List all DynamoDB tables in the configured AWS region.

Returns table names with pagination support. Use this as a starting point to discover available tables before querying or scanning.

When to use:

• To discover which tables exist in the account

• To find a table name before using describe_table, query_table, or scan_table

Returns: JSON with 'table_names' list, 'count', and optional 'next_table_name' for pagination.

Get detailed information about a DynamoDB table's schema and configuration.

Returns key schema, attribute definitions, GSIs/LSIs, billing mode, item count, table size, and table status.

When to use:

• To understand a table's key schema before querying

• To check what GSIs exist before creating a new one

• To verify table status (ACTIVE, CREATING, UPDATING, etc.)

• To check item count and table size

When NOT to use:

• To list tables (use list_tables instead)

Returns: JSON with table name, status, key schema, attribute definitions, indexes, billing mode, item count, and size in bytes.

Create a new DynamoDB table.

Creates a table with a partition key and optional sort key. Defaults to on-demand billing (PAY_PER_REQUEST). Use describe_table to monitor the table until it reaches ACTIVE status.

When to use:

• To create a new table for storing data

• When setting up a new access pattern

When NOT to use:

• If the table already exists (check with list_tables or describe_table first)

Returns: JSON with table name, status, key schema, and billing mode.

Create a Global Secondary Index (GSI) on a DynamoDB table.

GSIs enable querying on non-primary-key attributes. The table must be in ACTIVE status. Index creation is asynchronous — use describe_table to monitor progress.

When to use:

• To enable queries on attributes that aren't part of the primary key

• To create alternative access patterns for existing data

When NOT to use:

• If a suitable GSI already exists (check with describe_table first)

• If the table is not in ACTIVE status

Returns: JSON confirming the GSI creation was initiated with index details.

Add (put) a single item to a DynamoDB table.

Creates a new item or replaces an existing item with the same primary key. Use condition_expression='attribute_not_exists(PK)' to prevent overwrites.

When to use:

• To create a new item in a table

• To replace an entire existing item

When NOT to use:

• To update specific attributes (use update_item instead)

• To add many items at once (use bulk_add_items instead)

Returns: JSON confirmation with the item's primary key.

Delete a single item from a DynamoDB table by its primary key.

The item is permanently removed. Use condition_expression to ensure the item exists before deleting.

When to use:

• To remove a specific item from a table

• When you know the item's full primary key

When NOT to use:

• To delete all items (use prune_table instead)

• To delete by non-key attributes (scan first, then delete)

Returns: JSON confirmation with the deleted item's key.

Update specific attributes of an item in a DynamoDB table.

Modifies only the specified attributes without replacing the entire item. Supports SET, REMOVE, ADD, and DELETE operations in the update expression. Returns the updated item's attributes.

When to use:

• To modify specific attributes of an existing item

• To increment counters (SET count = count + :inc)

• To add/remove elements from sets

• To remove attributes from an item

When NOT to use:

• To replace an entire item (use add_item instead)

• To update many items at once (iterate with update_item or use bulk operations)

Returns: JSON with the updated item attributes.

Add multiple items to a DynamoDB table in efficient batches.

Uses batch_writer which automatically handles batching (25 items per batch), retries on unprocessed items, and flushing. Items with the same primary key will overwrite existing items.

When to use:

• To add many items at once (more efficient than repeated add_item calls)

• For data loading or migration scenarios

When NOT to use:

• For a single item (use add_item instead)

• When you need conditional writes (batch_writer doesn't support conditions)

Returns: JSON confirmation with the count of items added.

Delete all items (or filtered items) from a DynamoDB table.

Scans the table and batch-deletes all matching items. The table itself is preserved — only items are removed. Requires confirm=true.

WARNING: This is a destructive operation. Without a filter_expression, ALL items in the table will be permanently deleted.

When to use:

• To clear all data from a table while keeping the table structure

• To delete items matching specific criteria (with filter_expression)

• For test data cleanup

When NOT to use:

• To delete the table itself (not supported by this server)

• To delete a single item (use delete_item instead)

Returns: JSON with the count of items deleted.

Query a DynamoDB table using key conditions to find matching items.

Queries are efficient because they use the table's primary key or GSI/LSI keys. Results are returned sorted by sort key. Optional filter expressions can further refine results (but don't reduce read capacity consumed).

When to use:

• To find items by primary key (partition key + optional sort key condition)

• To find items using a GSI or LSI

• When you know the partition key value

When NOT to use:

• When you don't know the partition key (use scan_table instead)

• For full-table searches (use scan_table with filter)

Returns: Items matching the query with count, scanned_count, and pagination key. Format controlled by 'format' parameter (json or markdown).

Scan a DynamoDB table to read all items, optionally filtering results.

Scans read every item in the table (or index), consuming read capacity proportional to table size regardless of filters. Use queries when possible.

When to use:

• To browse all items in a table

• When you don't know the partition key value

• For ad-hoc searches across all items

When NOT to use:

• When you know the partition key (use query_table — much more efficient)

• For large tables without filters (expensive and slow)

Returns: Items from the scan with count, scanned_count, and pagination key. Format controlled by 'format' parameter (json or markdown).