Gulliver

gulliver_review

Read-only

Reviews SQL and dbt model changes before a PR: compares base vs head, flags new lint, classifies change type, lists breaking downstream models, and estimates scan and cost before vs after.

Instructions

PR gate for SQL models: for each .sql model changed between a base ref and head (git) or between two dbt manifests, report new scale lint, the change type (cosmetic, non_breaking, breaking), the downstream models that break and, with a connection, the scan and money per run and per month before vs after (estimates). rehearse=true also runs 1% and 3% samples to catch new row explosions. status 'block' means the [review] policy says do not merge. Call before opening a PR. Reads git or the manifests and, with a connection, estimates without running (except rehearse=true). Use gulliver_impact for one table or column, gulliver_lint for one query.

Input Schema

Name	Required	Description	Default
`base`	No	Base ref to compare against, e.g. 'origin/main'.	origin/main
`head`	No	Head ref (only committed changes are reviewed).	HEAD
`markdown`	No	Also return the PR-comment markdown.
`rehearse`	No	Also run changed models on 1% and 3% samples (budget-checked; costs money on billed engines).
`connection`	No	Connection name as listed by gulliver_status (from gulliver.toml or GULLIVER_DSN). Omit for the default connection.
`models_dir`	No	Folder with SQL models (*.sql, dbt-style refs allowed). Use an absolute path.
`manifest_base`	No	dbt manifest.json of the base build (instead of git).
`manifest_head`	No	dbt manifest.json of the branch.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.1Nov 3, 2026

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."

Addedv0.1.1Nov 3, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Beyond the annotations, it discloses that estimation normally does not execute queries, that rehearse=true is the exception and costs money on billed engines, and that only committed changes are reviewed. The readOnlyHint=true annotation remains consistent since rehearsals are sample reads, but the description could have been explicit about that boundary to avoid any question.

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?

It is dense and front-loaded, leading with the purpose and ending with alternative routing. The telegraphic style occasionally compresses several ideas into one sentence, but almost every clause carries information an agent needs.

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, so return-value detail is unnecessary, and the description still covers the meaningful output categories, the block policy, cost implications, and input-mode choice. Nothing required to invoke it correctly is missing.

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 100%, so the baseline is 3; the description still adds value by explaining the intent of rehearse (1% and 3% samples to catch row explosions) and by framing base/head as a git-vs-manifest choice. The markdown parameter is not mentioned, which is the one small gap.

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 first clause names a concrete verb and resource ('PR gate for SQL models') and the rest specifies the exact comparison inputs (base ref/head in git, or two dbt manifests) and the report contents (scale lint, change type, downstream breakage, scan/money estimates). It is clearly distinguishable from gulliver_diff, gulliver_impact, and gulliver_lint.

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?

It states an explicit trigger ('Call before opening a PR') and routes the agent away from siblings by name: gulliver_impact for a single table/column, gulliver_lint for a single query. It also defines the operational meaning of the output ('status block means the [review] policy says do not merge').

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

Deploy Server