Skip to main content
Glama
Sign In
Gulliver

Gulliver

by laaielichter
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

gulliver_preflight

Read-onlyIdempotent

Estimate SQL query bytes, rows and cost without executing it, then get scale lint and a budget verdict with status and next step.

Instructions

Estimate bytes, rows and money for a query WITHOUT running it (BigQuery dry-run, EXPLAIN elsewhere; free), plus scale lint and the budget verdict. Every estimate says how exact it is (exact, upper_bound or heuristic). status is ok, warn, block, needs_rehearsal or needs_approval, with next_step. Always call before gulliver_run. Use gulliver_rehearse instead when the estimate is a heuristic or joins may multiply rows. Logs a receipt for gulliver_receipt.

Input Schema

NameRequiredDescriptionDefault
sqlYesExactly one SQL statement (SELECT/WITH) in the connection's dialect. Several statements are rejected.
connectionNoConnection name as listed by gulliver_status (from gulliver.toml or GULLIVER_DSN). Omit for the default connection.

Output Schema

NameRequiredDescriptionDefault
statusYes
next_stepYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.1
    • changedInput schema / properties / connection / description
      Previous value: -"Connection name from gulliver_status. Omit for the default."New value: +"Connection name as listed by gulliver_status (from gulliver.toml or GULLIVER_DSN). Omit for the default connection."
    • changedInput schema / properties / sql / description
      Previous value: -"One SQL statement in the connection's dialect."New value: +"Exactly one SQL statement (SELECT/WITH) in the connection's dialect. Several statements are rejected."
  2. Changed3 schema fields changedv0.1.1
    • addedOutput schema / properties
      Added value: +{
+  "next_step": {
+    "type": "string"
+  },
+  "status": {
+    "enum": [
+      "ok",
+      "warn",
+      "block",
+      "needs_rehearsal",
+      "needs_approval",
+      "skipped",
+      "fail",
+      "error"
+    ],
+    "type": "string"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "status",
+  "next_step"
+]
    • changedOutput schema / title
      Previous value: -"gulliver_preflightDictOutput"New value: +"GulliverResult"
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description adds substantial context beyond them: the query is never executed, the estimate is free, every estimate carries an exactness label (exact, upper_bound, heuristic), and the status vocabulary plus next_step are disclosed. It also notes a side effect the annotations do not imply — a receipt is logged for gulliver_receipt — which is exactly the kind of hidden behavior an agent needs.

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 core action and mechanism, and no sentence is filler — each adds a rule, a status vocabulary, or a routing hint. It is dense with parentheticals and packed clauses, which slightly hurts scannability for a two-parameter call.

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 explains the status values and exactness labels an agent must interpret, plus the receipt side effect and the rehearse fallback. For a preflight/gating tool nothing needed to call it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and both parameters (sql, connection) are documented in the schema, so the baseline applies. The description adds no syntax, dialect, or multi-connection nuance beyond what the schema already says; the 'exactness' discussion is about output, not input.

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 ('Estimate bytes, rows and money for a query') and immediately scopes it as non-executing via the BigQuery dry-run / EXPLAIN mechanism. It also names the extra outputs (scale lint, budget verdict) so the agent knows this tool is broader than a plain cost estimate.

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 prerequisite ('Always call before gulliver_run') and an explicit alternative rule ('Use gulliver_rehearse instead when the estimate is a heuristic or joins may multiply rows'). Both the when and the when-not are stated with the sibling named.

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

Deploy Server

Other Tools