Skip to main content
Glama

Validate SQL without running it

pg_validate_sql
Read-onlyIdempotent

Validate read-only SQL without executing it: check syntax, object names, safety rules, result columns/types, touched tables, and cost estimate. Test queries or diagnose why pg_query refuses them.

Instructions

Check a read query without executing it: syntax, object names, safety rules, result columns with types, tables it would touch and its estimated cost.

Use it to test SQL you are about to give to the user, or to see exactly why pg_query would refuse a statement.

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

Input Schema

NameRequiredDescriptionDefault
sqlYes
paramsNo
connectionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds meaningful behavior beyond that: the statement is never executed, and the validation covers object names, safety rules, typed result columns, touched tables and estimated cost — useful disclosure given there is no output schema. It does not say what happens when validation cannot resolve objects without a connection, which keeps it short of a 5.

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?

Two sentences, front-loaded with the core action, then a dense clause listing the checks and a second sentence giving the use cases. Every phrase carries information; nothing is redundant with the title.

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 usefully enumerates what the validation reports, which is the main completeness burden here. However, two of three parameters are left entirely unexplained and the shape of the validation result (pass/fail vs. structured report) is not described, leaving material gaps for a tool an agent must call correctly.

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

Parameters2/5

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

Schema description coverage is 0% and there are three parameters including 'params' and 'connection', yet the description never mentions either. An agent gets no hint that 'params' presumably supplies bind values for placeholders or that 'connection' selects which database is used for name resolution. The description only implicitly covers the required 'sql' argument.

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 a specific verb and object ('Check a read query without executing it') and then enumerates exactly what is checked: syntax, object names, safety rules, result columns with types, tables touched, and estimated cost. The reference to pg_query refusing a statement makes the boundary between this validator and the executing sibling explicit, 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 Guidelines4/5

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

It gives two concrete triggers: testing SQL before handing it to the user, and diagnosing why pg_query would reject a statement. The scoping word 'read query' implicitly excludes write statements, but no explicit when-not guidance or prerequisite (e.g. a required connection for object-name resolution) is stated.

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