SQLScope

Run SQL

query

Execute SQL statements against a connected database to retrieve data, inspect schemas, or return affected-row counts. Supports bound parameters and row caps for controlled results.

Instructions

Run a SQL statement. SELECT/SHOW/EXPLAIN return rows (capped by maxRows, default 1000); INSERT/UPDATE/DELETE return affected-row counts; multi-statement scripts are supported where the driver allows them. Params bind with ? (array) or :name (object) where supported.

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": "query"
  }
}

Input Schema

Name	Required	Description
`sql`	Yes	SQL statement or script to run
`params`	No	Bound parameters: array for positional placeholders (?), object for named ones (:name) where the driver supports them.
`maxRows`	No	Row cap for this query only (server default: 1000)
`connection`	No	Named connection to use. Omit when only one connection is configured (or it is named "default").

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Sep 8, 2026

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does this well by explaining return shapes per statement type, the maxRows cap/default, multi-statement script support, and parameter binding conventions. It stops short of discussing side effects or permissions, but the core runtime behavior is transparent.

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?

Three dense, well-structured sentences with no filler. The purpose is front-loaded, behavior is grouped logically, and every sentence contributes information.

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 general SQL execution tool with no output schema and no annotations, the description covers the essential decision factors: return modes, row limits, binding syntax, and multi-statement support. It leaves some room for connection-selection details, but those are documented in the schema.

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 already 100%, giving the baseline of 3. The description adds useful semantics beyond the schema by connecting sql statement categories to their return behavior and clarifying maxRows as a per-query cap with a default of 1000.

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?

The description opens with 'Run a SQL statement', giving a clear verb and resource, then distinguishes this general-purpose execution tool from the specialized siblings list_tables, describe_table, sample_rows, and explain_query by covering the statement types it handles.

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?

The description clearly conveys that this is the tool for arbitrary SQL execution and enumerates which statement categories it supports. It does not name sibling alternates explicitly, but the practical context is strong enough for an agent to choose it over the specialized table-introspection siblings.

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

Deploy Server