Skip to main content
Glama
sql-mcp
by ohankay

execute_sql

Destructive

Execute T-SQL queries and scripts against SQL Server, including SELECT, DML, DDL, and stored procedures, returning result sets, messages, and errors.

Instructions

Execute any T-SQL: SELECT, INSERT/UPDATE/DELETE/MERGE, DDL (CREATE/ALTER/DROP), EXEC, DBCC, BACKUP, ...

  • Scripts may contain GO batch separators (GO n repeats). CREATE PROCEDURE/VIEW/FUNCTION/TRIGGER must be alone in its batch.

  • params: values for ? placeholders (single batch only), e.g. sql="SELECT * FROM t WHERE id = ?", params=[5].

  • database: run in this database (the connection's previous database is restored afterwards).

  • max_rows: per result set (default from the profile, 1000). continue_on_error: keep running later batches.

  • output_format: 'json' (default) or 'markdown'. Returns result_sets, rows_affected, messages (PRINT / info), errors, open transaction warnings.

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

Input Schema

NameRequiredDescriptionDefault
sqlYes
paramsNo
databaseNo
max_rowsNo
connectionNo
output_formatNojson
timeout_secondsNo
continue_on_errorNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: the database context is restored afterwards, max_rows defaults to 1000 via the profile, continue_on_error controls later batches, and open transaction warnings come back in the response. It stops short of stating permission requirements, transaction-commit semantics, or explicitly warning that DDL/DROP is irreversible, which matters for a destructive arbitrary-SQL tool.

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?

Front-loaded with the verb and resource, then a compact bulleted list that assigns one line per parameter and one for the return shape. The telegraphic style slightly hurts readability, but nearly every clause carries information an agent could not get from the schema.

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 an 8-parameter tool with no output schema and destructive capability, the description covers return values (result_sets, rows_affected, messages, errors, transaction warnings), batching rules, and most parameters. The gaps are connection (useful when multiple connections exist, as add_connection/list_connections imply) and timeout_seconds, plus no statement about transaction side effects.

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

Parameters5/5

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

With 0% schema description coverage across 8 parameters, the description carries the full burden and mostly succeeds: sql, params (with a concrete placeholder example and the single-batch restriction), database (and its restore behavior), max_rows (unit = per result set, default source), continue_on_error, and output_format ('json' default vs 'markdown') are all explained with meaning the schema does not contain. Only connection and timeout_seconds go undocumented.

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?

States a specific verb and full resource scope ('Execute any T-SQL'), enumerating the statement classes it accepts (DML, DDL, EXEC, DBCC, BACKUP). An agent knows exactly what it does, but the description never distinguishes it from the sibling execute_procedure, which is the one real ambiguity given overlapping scope.

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

Usage Guidelines3/5

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

Usage is implied broadly ('any T-SQL'), and it does supply the constraint that CREATE PROCEDURE/VIEW/FUNCTION/TRIGGER must be alone in a batch and that params only work in a single batch. However there is no explicit when-not guidance: nothing tells the agent to use execute_procedure for stored procs, begin_transaction/commit_transaction for transaction management, or describe_table for schema inspection.

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