Execute a two-phase distributed commit across multiple database stores using an authorized dry-run token, enabling atomic multi-store changes with rollback preview.
Execute two-phase distributed commit across multi-store environments using an authorized distributed dry-run token.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | ||
| operations | Yes |
Changes observed during successful MCP inspections.
v0.2.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. It does disclose two behavioral facts beyond the schema: 'two-phase' implies atomicity semantics and 'authorized ... token' implies an authorization prerequisite. It omits critical traits for a destructive multi-store write: what happens on partial failure, whether the commit is all-or-nothing, idempotency, and irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler; the operation, scope, and authorization mechanism all appear before any trailing clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, cross-store, two-phase commit with a nested operations array, no annotations, no output schema, and 0% parameter coverage, the description is far too thin. An agent cannot determine failure semantics, per-store targeting, or what the commit returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning for either parameter. It never explains that 'token' must be a dry-run-issued authorization token or that 'operations' is an array of per-store actions (SQL, KV_SET, KV_DEL, KV_EXPIRE) with storeId/storeType/queryOrKey. The nested operation structure is left entirely to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific operation and scope: 'Execute two-phase distributed commit across multi-store environments.' This distinguishes it from siblings like db_commit (single-store) and db_distributed_dry_run (the preview step), though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'using an authorized distributed dry-run token' implies a prerequisite: you must first run a distributed dry-run to obtain the token. That is an implied usage condition rather than an explicit one, and the description never states exclusions or directly names db_distributed_dry_run as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.