Tools reference

The server exposes 35 typed tools. Each one names an effect, which decides the rung it needs, and some name a plan feature on top of the MCP Server gate every call checks first. Permissions and refusals explains the effects and the ladder.

Effects in these tables are Read, Local write for Dynomatic’s own database, and Remote write for anything that reaches your AWS account.

The server’s own instructions tell an agent to start with list_profiles, pass a profile name back exactly as returned, then list_tables and describe_table before reading items. They also tell it that a table whose items have been embedded answers questions about what they say through semantic_search rather than scan. Item values are DynamoDB JSON throughout, so {"S": "..."} and {"N": "..."} rather than plain values.

Worked examples has a real transcript for most of the tools below, captured against the Sample mode tables.

App and profiles

Tool	Effect	Gate	What it returns
app_status	Read	none	Dynomatic’s version, whether Sample mode is active, the effective feature gates, and what the server is currently allowed to do
list_profiles	Read	none	The AWS profiles Dynomatic knows, managed and from ~/.aws. Its profile value is what every other tool takes
profile_status	Read	none	Whether a profile has cached credentials this session and which account it resolved to. Makes no network call

Tables

Tool	Effect	Gate	What it returns
list_tables	Read	none	Every table name in a profile and region
describe_table	Read	none	Key schema, attribute definitions, indexes, item count, size, billing, streams and TTL, plus embeddings: the attributes this table has embedded, which semantic_search can search by meaning. Empty on a table with no vectors
create_table	Remote write	Table CRUD	Creates a table from a CreateTable request in its AWS spelling, and returns the description AWS answers with
delete_table	Remote write	Table CRUD	Deletes a table and every item in it

Items

Tool	Effect	Gate	What it returns
get_item	Read	none	One item by its full primary key, or no item when the key does not exist
batch_get_items	Read	none	Up to 100 items from one table by their keys. A key that matches nothing is absent from the answer, and the order does not follow the keys
put_item	Remote write	none	Writes one whole item, replacing any item with the same key
update_item	Remote write	none	Sets and removes named attributes on one existing item, leaving the rest alone
delete_item	Remote write	none	Deletes one item by its key. Deleting a key that does not exist succeeds
batch_write_items	Remote write	Bulk Actions	Up to 500 puts and deletes in one table. Puts run before deletes, and a failure part way through leaves the earlier writes in place

Queries

Tool	Effect	Gate	What it returns
query	Read	none	One page of a DynamoDB Query on a table or index, with LastEvaluatedKey to pass back as cursor
scan	Read	none	One page of a Scan. The description tells an agent to prefer query when a key condition is known

PartiQL

Tool	Effect	Gate	What it returns
partiql	Read or remote write, from the statement	PartiQL	Runs one statement. SELECT reads, INSERT, UPDATE and DELETE write, anything else is refused

Vector search

Tool	Effect	Gate	What it returns
semantic_search	Read	Vector Search	The items closest in meaning to a plain-language text, scored and ranked, with the index and model that answered. Needs a table with an embedding recipe, which describe_table reports under embeddings

scoreDirection says which way to read the score, because a cosine index scores distance and a lower number is a closer match. Where the vector index partitions on an attribute, SearchVectors searches one partition at a time, so the call takes a partition value and a call without one is refused with the attribute’s name. A refusal from this tool has the kind NotSearchable and a reason. The NotSearchable reasons lists the six.

Embeddings covers how a table gets vectors, and Ask what the items say is the whole flow end to end.

Schema and data model

Tool	Effect	Gate	What it returns
schema_profile	Read	none	What Dynomatic has learned about a table from the items it has seen: key schema, indexes, observation count, the most common attributes, detected entities, and sibling tables in the same group. Errors when the table has never been observed
data_model	Read	Data Model	The table’s stored data model, as the Data model tab shows it. Returns dataModel: null when it has never been inferred, and never infers on its own
infer_data_model	Local write	Data Model	Runs inference over what Dynomatic has observed and stores the result, replacing any previous one. This is the Re-infer action
import_schema	Local write	Schema Import	Reads an ElectroDB or DynamoDB Toolbox schema from your own source files and returns it normalized. It saves nothing into Saved Schemas, which is still the wizard’s job

Saved queries and scripts

Tool	Effect	Gate	What it returns
list_saved_queries	Read	none	The queries saved in the workspace for a profile and region. Errors when there is no workspace for that pair, which is a different answer from a workspace with nothing saved
save_query	Local write	Saved Queries	Saves a query into the workspace, where it appears in the saved-query list. Pass id to overwrite
list_saved_scripts	Read	none	Every script saved in Dynomatic, across every workspace, with its code and language

Scripts

Tool	Effect	Gate	What it returns
run_script	Remote write	Scripting	Runs TypeScript or Python in Dynomatic’s sandbox with the DynamoDB bridge bound to a profile and region, and returns the value plus the console output. One at a time, so a second call is refused rather than queued

Exports and jobs

Tool	Effect	Gate	What it returns
export_start	Local write	none	Streams a whole Scan or Query to a file in the background and returns a job id
export_status	Read	none	What a job is doing, or the file it wrote. A finished job answers for an hour
export_cancel	Read	none	Stops a running export and leaves its partial file and checkpoint in place

Exports and show in the app covers the job lifecycle in full.

Streams

Tool	Effect	Gate	What it returns
stream_records	Read	Streams Viewer	Stream records Dynomatic has already cached for a stream, newest first, within a millisecond window, with a cursor and per-event-type totals. It reads that cache rather than polling AWS, so a stream this session never drained comes back empty

Environment

Tool	Effect	Gate	What it returns
environment_report	Read	none	Every profile and table Dynomatic has classified, with its environment, confidence, and whether the profile mixes environments

Templates

Tool	Effect	Gate	What it returns
render_template	Read	none	Resolves a ${[ … ]} template against the variables for a profile, region and table, so you can see what a query will send

Warning: render_template resolves a secure value to plaintext in its answer, the same exposure PartiQL statement rendering has. An agent that can reach the tool can read those secrets.

Show in the app

Tool	Effect	Gate	What it does
show_table	Read	none	Opens a table on the tab bar with the agent’s query filled into the query builder, for you to run
show_item	Read	none	The same, for one item by its key, and selects that row in the grid once it is there

Both read nothing and change nothing, so they work while the server is read-only. Exports and show in the app covers why the query is filled in but never run.

Any command

Tool	Effect	Gate	What it does
list_commands	Read	none	Every command Dynomatic registers, with its effect, gates, argument names, and whether it can run here
invoke_command	Whatever the command is	The command’s own	Runs one of the commands list_commands reports as runnable, under the same ladder

Any command, through one tool covers both.

Table resources

A table’s schema and data model are also addressable as resources, so a client that reads resources can pull one into a conversation by URI.

dynomatic://table/{profile}/{region}/{name}/schema
dynomatic://table/{profile}/{region}/{name}/data-model

A resource read runs the same call the matching tool runs, clears the same policy and the same gate, and answers the same payload. It also counts as one of the session’s calls, taking a concurrency slot and running under the 60 second ceiling.

Note: Dynomatic advertises these two templates and no concrete resources, because listing every table in every profile would cost an AWS call per listing. A client’s resource picker expands concrete resources, not templates, so it shows nothing for Dynomatic. Type or paste the URI instead, with a real profile, region and table name in place of the braces.

Result caps and cursors

Any answer over 4 MB is cut down, marked truncated: true, and says in droppedItems how many items went, so an agent knows how much narrower to make the next request. A page that had a LastEvaluatedKey keeps it, so a continuation still lands after the page. A page that had none, which happens with PartiQL, has no continuation to offer and the dropped items are unreachable from that answer.

Each answer sheds its least useful part first. environment_report drops individual table rows before the profile rows every table falls back on. run_script drops its printed log before the value the script returned.

In practice query and scan never reach the cap, because DynamoDB caps a page at about 1 MB of item data. The cap bites on the tools with no paging underneath them, which are partiql, schema_profile, data_model, stream_records, list_saved_scripts and environment_report. semantic_search has none either, and its topK of at most 100 is what keeps it small.