cost-guard-mcp

Overview Schema Source Related Servers Discussions Admin

estimate_query_cost

Read-only

Estimate a SQL query's cost before execution to avoid expensive runs. Returns a dollar figure with an accuracy tier (PRECISE, UPPER_BOUND, or HEURISTIC).

Instructions

Estimate the cost of a SQL query before running it. ALWAYS call this before running an expensive-looking query. The response's accuracy_tier tells you how much to trust the number: PRECISE (exact), UPPER_BOUND (real cap, may overstate), HEURISTIC (rough). Accepts exactly one SQL statement per call (a single trailing ';' is fine) - text with more statements is refused before anything is estimated. This tool accepts only read statements (first keyword SELECT, WITH, VALUES, SHOW, DESCRIBE, DESC or EXPLAIN; a WITH must lead to a SELECT or VALUES) - others are refused before anything is estimated. Operator opt-out: COST_GUARD_ALLOW_WRITE_STATEMENTS=1.

warehouse_size (Snowflake/Databricks only, e.g. "SMALL", "X-Large") and edition
(Snowflake only, e.g. "enterprise") can only raise the estimate: the dollar figure is
priced at the warehouse the query is pinned to as the server observes it (its size, type
and generation) and at the operator-configured edition, whichever is higher. Warehouse
types without a modelled rate (Snowpark-optimized, Databricks Classic/Pro) get no dollar
figure.

Compute disclosure: on Snowflake and Databricks the EXPLAIN and the warehouse/history
metadata lookups run on the named (or default/configured) warehouse session, which could
resume a suspended or start a stopped warehouse and bill compute. By default the server
reads the warehouse's state first (Snowflake: the SHOW WAREHOUSES row, after USE WAREHOUSE,
EXPLAIN USING JSON and SELECT CURRENT_WAREHOUSE() when no warehouse argument names one;
Databricks: a control-plane GET through the Warehouses API, before any session): on a
Snowflake warehouse that is not STARTED the cloud-provider (SELECT CURRENT_REGION()) and
query-history lookups are skipped and the estimate says so in a caveat (Gen1 rates,
heuristic runtime; the query-history lookup is also skipped when no warehouse argument is
given); on a Databricks warehouse that is not RUNNING, or whose state cannot be read, no
session is opened and the estimate carries no byte or dollar figure. Operator opt-ins:
COST_GUARD_SNOWFLAKE_ALLOW_WAREHOUSE_RESUME=true,
COST_GUARD_DATABRICKS_ALLOW_WAREHOUSE_START=true. run_query_bounded is not gated.

Input Schema

Name	Required	Description	Default
`sql`	Yes
`engine`	Yes
`edition`	No
`warehouse`	No
`warehouse_size`	No

Output Schema

Name	Required	Default
`engine`	Yes
`caveats`	No
`currency`	No	USD
`accuracy_tier`	Yes
`estimated_bytes`	No
`estimated_cost_usd`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.1Sep 15, 2026

addedInput schema / properties / edition

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Edition"
+}

addedInput schema / properties / warehouse_size

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Warehouse Size"
+}

First observedv0.1.0Sep 12, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only give readOnlyHint and openWorldHint, but the description discloses far more: accepted statement types, refusal behavior, the accuracy_tier trust model, that warehouse_size/edition can only raise the estimate, that unmodelled warehouse types yield no dollar figure, and the critical side effect that EXPLAIN/metadata lookups can resume or start a warehouse and bill compute. That compute-billing disclosure is exactly the kind of consequence an agent cannot infer from the annotations.

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

Conciseness3/5

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

The opening two sentences are ideally front-loaded, but the 'Compute disclosure' block is a dense run-on with stacked parentheticals (region lookup, SHOW WAREHOUSES row, CURRENT_WAREHOUSE, Gen1 caveats) that is hard to parse and largely operational trivia. Much of it is genuinely load-bearing for billing risk, yet it could be halved without losing decision-relevant information.

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?

An output schema exists and the description still usefully names the accuracy_tier values and their trust levels and mentions caveats, so return semantics are covered. For a tool with 5 params, no schema descriptions, and real billing side effects, the definition leaves an agent with everything needed to call it correctly and safely.

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 carry the params, and it does well for warehouse_size ('Snowflake/Databricks only, e.g. SMALL, X-Large') and edition ('Snowflake only, e.g. enterprise'), plus the semantics of the sql constraint. The warehouse parameter is only referenced obliquely ('when no warehouse argument names one') and engine gets no prose at all, so the coverage is strong but not complete.

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+resource ('Estimate the cost of a SQL query before running it') and immediately positions itself relative to the sibling by noting 'run_query_bounded is not gated.' An agent can distinguish it from run_query_bounded, check_credentials, and describe_engine_capabilities without opening any 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?

Explicit trigger ('ALWAYS call this before running an expensive-looking query'), explicit exclusions (multi-statement text and non-read statements are refused before estimation), and an explicit escape hatch (COST_GUARD_ALLOW_WRITE_STATEMENTS=1). This is a textbook when/when-not/alternatives section.

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

Deploy Server