Skip to main content
Glama

Run SQL that changes data

execute_write_query
Destructive

Run one SQL statement that changes data or structure (INSERT, UPDATE, DELETE, CREATE and so on) on a connection whose aiAccess is same_as_people, and return its result in the same shape as execute_query. Only use it when the user has asked for the change; for reading, use execute_query. Refused on every other connection, and on a connection the team made read-only for people too. DROP DATABASE, DROP SCHEMA and TRUNCATE are always refused. Counts against the company's monthly query quota and a limit of 30 queries per minute (the team can set a lower one per connection). Needs the execute scope and a member role that can edit. The team can require a person to approve some requests: the call then fails with code APPROVAL_REQUIRED and an approvalUrl. Show the user that link, wait until they say it is approved, then repeat the exact same call with approvalId. An approval works once, for that SQL, within 30 minutes.

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

Input Schema

NameRequiredDescriptionDefault
sqlYesThe SQL statement to run, in the connection's own dialect.
approvalIdNoOnly when repeating a call that came back with APPROVAL_REQUIRED, after the user approved it. Send the same arguments again.
connectionIdYesConnection id from list_connections.

Output Schema

NameRequiredDescriptionDefault
resultNo
successNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond the destructiveHint=true annotation: it names the connection precondition, the permanently refused statements, quota and rate-limit exposure (monthly quota, 30 queries/minute with a lower per-connection cap), the execute scope plus member role requirement, and a full approval workflow with the APPROVAL_REQUIRED error code, approvalUrl, approvalId replay, single-use semantics, and a 30-minute expiry. This is exactly the operational context annotations cannot carry.

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

Conciseness5/5

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

The paragraph is long but front-loaded with the core action and the alternative, and every subsequent sentence carries a distinct constraint (refusals, quota, permissions, approval loop). No filler or restatement of the name/title.

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

Completeness5/5

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

For a destructive, rate-limited, permission-gated write tool with three parameters, the description covers gating, failure modes, and the recovery loop; since an output schema exists it correctly delegates return shape to execute_query rather than duplicating it.

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 coverage is 100%, so the baseline is 3; the description still adds workflow meaning for approvalId that the schema only states in the abstract — repeat the exact same call with the id, it works once, for that SQL, within 30 minutes. sql and connectionId gain little beyond the schema, so it is a modest but real improvement over baseline.

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?

States a specific verb and resource ('Run one SQL statement that changes data or structure') with the exact statement classes it covers (INSERT, UPDATE, DELETE, CREATE). It explicitly contrasts itself with the sibling execute_query, so an agent can pick between them without opening either schema.

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?

Gives an explicit use condition ('Only use it when the user has asked for the change'), an explicit alternative for the opposite case ('for reading, use execute_query'), and hard exclusions (refused on non-same_as_people connections, read-only connections, and DROP DATABASE / DROP SCHEMA / TRUNCATE). Nothing about when to invoke is left to inference.

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