db-conn-mcp

Overview Schema Source Related Servers Discussions Admin

execute_write_query

Run INSERT, UPDATE, DELETE, or DDL statements on a write-mode database with a required dry-run preview and rollback before committing changes.

Instructions

Run an INSERT/UPDATE/DELETE/DDL statement on a write-mode database.

Know the schema before you write: if the exact table and column names are not already in this conversation, call get_table_schema first instead of guessing — a wrong name wastes a whole dry-run round-trip. Don't re-fetch a schema you already have.

SAFETY — the server enforces this flow; you cannot skip it silently:

Call with dry_run=true (the default): the statement executes inside a transaction and is ALWAYS rolled back, returning the rows_affected it WOULD have had. This records a preview grant for this exact statement.
Show the user the exact SQL and the dry-run result; ask for permission (not needed if the database has yolo enabled).
Call again with dry_run=false (and user_consent=true unless yolo) to commit. Commits without a prior dry-run of the identical statement are REJECTED. The preview grant expires 10 minutes after the dry-run and is consumed by the commit ATTEMPT it authorizes — including a commit that FAILS, which may still have applied server-side, so you MUST dry-run again before retrying. Running the same statement twice means previewing it twice. Pass skip_dry_run=true ONLY if the user explicitly asked to skip the preview.

Pass values via params ($1/$2/... placeholders), not pasted into the SQL.

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": {
      "database": "<database>",
      "sql": "<sql>"
    },
    "name": "execute_write_query"
  }
}

Input Schema

Name	Required	Description	Default
`sql`	Yes
`params`	No
`dry_run`	No
`database`	Yes
`timeout_ms`	No
`skip_dry_run`	No
`user_consent`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 5, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations supplied, the description carries the full behavioral burden and does so in detail: dry-run always rolls back and returns would-be rows_affected, a preview grant is recorded, commits without a matching dry-run are REJECTED, the grant expires in 10 minutes, and the grant is consumed by the commit attempt including failures. It also warns that a failed commit may still have applied server-side, which is exactly the kind of non-obvious hazard an agent cannot infer.

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?

Well front-loaded: purpose first, then schema prerequisite, then a numbered SAFETY flow, then a final invocation tip about params. The numbered structure makes a genuinely complex protocol skimmable. It runs long and a couple of lines restate earlier points (the retry/preview-twice note), but the density of unique information is high.

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

Completeness4/5

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

For a 7-parameter, high-risk mutation tool with no annotations and no output schema, the description covers the decision flow, the safety protocol, and the failure mode. The gaps are the undocumented timeout_ms parameter and no statement of what a successful dry_run=false commit returns, though rows_affected is at least described for the dry-run case.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate, and it explains the three non-obvious parameters thoroughly: dry_run (default true, always rolled back), skip_dry_run (only on explicit user request), and user_consent (unnecessary under yolo). It also explains params as $1/$2 placeholders rather than pasted literals. It leaves timeout_ms and the database parameter entirely undocumented, which is the remaining gap.

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

Purpose5/5

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

Opens with a precise verb plus resource scope: 'Run an INSERT/UPDATE/DELETE/DDL statement on a write-mode database.' This immediately separates it from the sibling execute_read_query and from schema-inspection tools, and the write-mode qualifier tells the agent which database is eligible.

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

Usage Guidelines5/5

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

Explicit routing rules are given: call get_table_schema first if table/column names are not already in the conversation, and don't re-fetch a schema you already have. It also names the exact escape hatch (skip_dry_run=true) and the narrow condition under which it applies, plus when user_consent is unnecessary (yolo mode).

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

This server cannot be deployed