Skip to main content
Glama

db_batch

Run multiple SQL statements as a single atomic transaction. Every statement commits together, or none do — a single failure rolls the entire batch back. Suited to any logical operation that spans more than one write (account deletion across multiple tables, moving money between rows, denormalized counters). Max 1000 statements per call.

Each statement returns its own { rows, count, changes, last_row_id } in results[i] matching the order you passed in.

Example (account deletion):

{
  "project_id": "my-saas",
  "statements": [
    { "sql": "UPDATE accounts SET status = 'deleted' WHERE id = ?", "params": ["u_abc"] },
    { "sql": "DELETE FROM sessions WHERE user_id = ?",            "params": ["u_abc"] },
    { "sql": "DELETE FROM posts WHERE author_id = ?",             "params": ["u_abc"] }
  ]
}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>",
      "statements": "<statements>"
    },
    "name": "db_batch"
  }
}

Input Schema

NameRequiredDescriptionDefault
draftNoAlias for the preview target flag.
targetNoDatabase target. Preview requires preview_session_id (or draft_id).
previewNoExplicit preview target flag. Cannot be combined with a production target.
draft_idNoAlias for preview_session_id.
preview_idNoOptional expected preview candidate release id.
productionNoExplicit production target flag. Cannot be combined with a preview target.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
statementsYesArray of { sql, params? } objects. Accepts a native JSON array; a JSON-stringified array is also accepted. Each runs atomically; any error rolls every statement back. Max 1000.
preview_session_idNoIdentifier for an active preview session's isolated database.
candidate_release_idNoAlias for preview_id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

B3.2/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses rich behavior well beyond the schema: all-or-nothing commit semantics, a 1000-statement cap, and per-statement result objects. But its flagship example performs `DELETE FROM sessions` and `DELETE FROM posts`, and the tool is explicitly sold as a way to delete accounts across multiple tables, while the annotations declare destructiveHint=false. An agent trusting that annotation would assume only additive changes and could run irreversible deletes; the conflict is a real safety mismatch rather than a cosmetic one.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The atomicity guarantee is front-loaded, followed by the cap, the return shape, and a worked example, so the reader gets the critical constraint first. The example is long for what it teaches, but each block does carry distinct information and nothing reads as boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly takes on the return contract and documents `{ rows, count, changes, last_row_id }` per statement in `results[i]`, which is genuinely necessary. However, it is silent on the production/preview targeting model that seven of the ten parameters implement, so an agent could submit a batch without understanding which database it will hit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the ten parameters (including the production/preview targeting flags and preview_session_id) are already documented in structured data, which sets the baseline at 3. The description adds the 1000-statement ceiling and a concrete `{ sql, params }` example, but says nothing about the production-vs-preview targeting parameters and clarifies nothing beyond the schema for project_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ("Run multiple SQL statements as a single atomic transaction") and immediately qualifies the atomicity model, so there is no ambiguity about what the tool does. It never names a sibling such as db_query, so the agent is left to infer that single-statement work belongs elsewhere; that keeps it out of the top band.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete when-to-use guidance ("any logical operation that spans more than one write") with three recognizable examples: account deletion across tables, moving money between rows, and denormalized counters. There is no explicit when-not-to-use statement (e.g. single statements, read-only queries, or schema changes that belong in db_migrate), so an agent must supply that exclusion itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources