Gulliver

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), it discloses the side effect that makes those hints true: the row count is persisted to the local .gulliver folder for the next max_change_pct comparison. It also discloses budget-checking behavior ('over budget returns block'), the all-checks-run guarantee, and how status 'fail' is derived. No contradiction with annotations, since the state change is local bookkeeping, not database mutation.

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

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

Front-loaded with what it does and the enumerated checks, then budget behavior, then side effects, then usage. It is dense but each sentence carries information; the long opening sentence is slightly run-on and pushes the constraint 'Give at least one check' near the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with full schema coverage, annotations, and an output schema, the description covers the remaining gaps an agent needs: cost/budget behavior, the persistence side effect, the fail semantics, and when to prefer a sibling. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds two things the schema cannot: the minimum-one-check constraint ('Give at least one check') and the cross-call semantics of max_change_pct, whose previous row count is stored from an earlier invocation. The other nine parameters are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first clause names a specific verb and resource ('Data quality checks on one table or query') and enumerates the exact check families (unique keys, not-null, accepted values, ranges, freshness, min rows, row-count change). It also distinguishes itself from gulliver_diff by naming that sibling explicitly, so an agent can choose 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.

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

It gives concrete timing guidance ('after a load or before trusting data') and routes comparison work to gulliver_diff. It does not address the other plausible alternatives (gulliver_lint, gulliver_preflight, gulliver_inspect), so the exclusion set is partial rather than complete.

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

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

Annotations already establish read-only and non-destructive, but the description adds substantial context the annotations cannot convey: comparison happens by key inside the engine via hashed buckets and scales to billions of rows, the two sides may live on different connections, and both queries are priced first so an over-budget run returns a status block rather than executing. That cost-gating behavior is critical for an agent to know before calling.

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

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

Front-loaded with the core question and then ordered from mechanism to outputs to budget behavior to sibling routing. The parentheticals ('hashed buckets, scales to billions of rows') are informative but make the first sentence dense; overall every sentence carries weight with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be enumerated, and the description still sketches what comes back (sample keys missing/extra/changed, or a status block when over budget). For a 6-parameter read-only diff tool with full schema coverage, nothing an agent needs 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.

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

Schema coverage is 100%, so every parameter including key, columns, connection and right_connection is already documented in the schema. The description reinforces that comparison is keyed and that sides may be on different connections, which explains why right_connection exists, but adds no format or syntax detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource framed as a question ('Data diff: do two queries or tables return the same rows?') and immediately names what it produces (sample keys missing, extra or changed). It is unambiguously distinct from gulliver_drift and gulliver_check, which are called out by name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly states the intended use case ('prove a refactor or migration keeps the same rows') and routes the agent to the correct siblings for adjacent needs: gulliver_drift for schema changes, gulliver_check for rules on a single table. This is textbook when-to-use/when-not-to-use guidance.

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

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

Adds substantial context beyond the annotations: the first call writes a snapshot file into the local .gulliver folder, later calls diff against it, and save=true replaces the baseline. It also resolves the otherwise confusing readOnlyHint=false by stating 'Only reads catalog metadata, never data' — the only writes are local snapshot files. Return/pagination behavior is not described, but an output schema exists to cover that.

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

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

Five tight sentences, front-loaded with the operation and only then the stateful caveats, then alternatives. Minor redundancy where 'tables and columns' is restated in parentheses, but nothing else is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a stateful, side-effecting-on-local-disk tool with four optional params and an output schema, the description covers what is inspected, what is written and where, what save changes, and how to pick sibling tools. Nothing an agent needs 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.

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

Schema coverage is 100%, so the baseline is 3, and the description earns an increment by explaining the stateful effect of save ('replaces it with the current schema' / keeping the same report) and by noting that the models/manifest path yields the list of broken models. Connection and models_dir are left to their schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Schema drift: compare the connection's tables and columns with the last snapshot', and enumerates exactly what drift means (added, removed, retyped columns and tables). It is clearly distinguishable from gulliver_diff (row comparison) and gulliver_impact (planning your own change), which are named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

States the positive use case ('Use it to catch upstream changes') and explicitly routes the agent elsewhere for the two most likely confusions: gulliver_impact for planning your own change and gulliver_diff for row comparison. A 'when-not' condition is effectively supplied by those alternative routes.

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

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

Beyond the annotations, the description discloses the key behavioral facts: with a connection it estimates before/after cost without reading data, verify runs in a private in-memory DuckDB that never touches the user's data, mode='all' deliberately changes results, and the tool never executes anything against the connection. These claims are fully consistent with readOnlyHint=true, destructiveHint=false and idempotentHint=true.

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

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

The purpose is front-loaded in the first clause, and every sentence carries new information (cost estimation, mode='all', verify, when to use). The dense run of parentheticals makes it slightly harder to scan than an ideal definition, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with an output schema, the description covers all the decision-relevant aspects: what it produces (SQL only), what it does not do (no execution, no data read), the risk profile of mode='all', and how verification works. The return-value shape is left to the output schema, which is appropriate.

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

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

Schema coverage is 100%, so the baseline is a 3, and the description meaningfully adds to it by explaining that mode='all' introduces result-changing rewrites (LIMIT, approx count, UNION ALL, NOT EXISTS), what verify=true actually does, and that supplying a connection enables cost estimation. It does not touch seed/cases/timezone/dialect semantics beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (rewrite SQL), the optimization goal (cheaper on big data / partition pruning) and gives a concrete before/after example (DATE(ts) = '...' becomes a range). It also distinguishes itself from siblings by naming gulliver_lint as the upstream diagnostics tool and by stating it 'only returns SQL and never runs it on the connection', which separates it from execution tools like gulliver_run.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives a clear trigger ('use after gulliver_lint finds results') and clarifies an important scope limit: the tool never executes the SQL. What is missing is an explicit when-not condition or a pointer to the next step in the workflow (e.g. gulliver_preflight/gulliver_rehearse/gulliver_run) for actually validating or executing the rewritten query.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds context not in annotations: it only parses files and needs no database, which tells the agent the tool is static and safe to call without connection setup, and it discloses the default graph-returning behavior when target is omitted. Return shape detail is left to the output schema.

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

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

Three tight sentences: capability first, default behavior second, environment constraint third, then routing guidance. No filler and nothing buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema covers return values and annotations cover the safety profile, so the description is close to complete. One small gap: with zero required parameters, it does not say what happens or fails if neither manifest nor models_dir is supplied, which an agent must infer.

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

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

Schema coverage is 100% and every parameter carries its own description, including target matching rules and manifest as an alternative to models_dir. The description reinforces the two-source idea (folder of SQL models or dbt manifest) but adds no syntax or precedence rules beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: downstream models and columns that use a table or table.column, computed as column-level lineage over SQL models or a dbt manifest. The no-target behavior (returns the model graph) is also stated, so the agent knows both modes without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives an explicit when: before changing or dropping a table or column. It also names two alternatives with their distinguishing conditions – gulliver_drift for changes already in the database, gulliver_review for a whole PR – so routing between siblings is unambiguous.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description reinforces with "never writes data" while adding genuinely new behavior: when a connection is supplied it issues exactly one budget-checked count query, so the agent knows there is a real (but bounded) database cost. It also explains that outputs are text artifacts rather than applied changes, and what not_safe implies. Minor gap: it does not say what happens when the connection is invalid or the count is refused by budget.

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

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

Two dense sentences plus a routing sentence, with purpose front-loaded. Slightly overloaded with parentheticals (the strategy list and the budget-checked query), but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema, rich annotations, and fully documented parameters, the description covers everything an agent needs: what it returns (classification, SQL/config text, optional row estimate), that it is non-mutating, and when to prefer a sibling.

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

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

Schema coverage is 100%, so the schema carries parameter definitions; the description still adds meaning beyond it by tying the connection parameter to an actual count query and clarifying that the cost estimate is opt-in. The strategy categories and not_safe semantics also explain why a unique_key/merge path exists.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb-and-resource: it classifies a rebuild-every-run model into one of four named strategies (append, partition_overwrite, merge_recompute, not_safe), emits incremental SQL plus dbt config as text, and optionally measures skipped rows. It also explicitly contrasts itself with a sibling (gulliver_fix for a single slow query), so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives an explicit use condition ("models that run on a schedule") and names the alternative (gulliver_fix) for the contrasting case (a single slow query). It also clarifies what to do with each outcome, e.g. not_safe means keep the full rebuild.

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

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

Annotations already cover read-only, idempotent, non-destructive safety. The description adds real context the annotations cannot: it reads catalog metadata only and costs nothing, with one disclosed exception (scan_rows runs one budget-checked sample query per table). It does not say how heavy that sample query is or what the limit budgets are, 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.

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

Front-loaded with the core action, then the mode split, then the cost caveat, then routing. It is dense but every clause carries information; the parenthetical about scan_rows is the one slightly awkward insert.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema supplied, the description does not need to explain return values, and for a read-only inspection tool with full parameter docs and annotations it covers everything an agent needs to call it correctly, including the one case that incurs query cost.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents every parameter including limit, table, scan_rows, sensitive and connection. The description adds one useful interaction detail (limit is not used when table is given) and clarifies the cost profile of scan_rows, but leaves sensitive and connection entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Explore a database before writing SQL') and immediately splits into two concrete modes: list biggest tables without a table argument, describe columns with one. It also names the sibling tools it is not (gulliver_preflight, gulliver_drift), so an agent can place it without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly says when to use it ('learn sizes and partition columns') and names two alternatives with their distinct jobs: preflight to price a specific query, drift to see schema changes over time. The no-table vs with-table branching is spelled out as well.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context. It does: no database connection is used, nothing is rewritten, and findings carry a severity plus a textual suggested fix. It stops short of describing pagination or the finding count, but the output schema presumably covers the shape.

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

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

Front-loaded with the core purpose and alternatives in three dense sentences with no filler. The rule enumeration in the parenthetical is long but justifies itself by showing rule scope; slight density is the only cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only lint tool with an output schema and full annotations, the description covers purpose, when to use, what is and isn't produced, and routing to the right sibling. Nothing an agent needs 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.

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

Schema coverage is 100%, so the sql and dialect parameters are already fully documented, including the enum and the note that some rules are engine-specific. The description adds only indirect signal (naming 'missing partition filter' as a rule), which the dialect description already explains. Baseline 3 for a schema that does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: static scale lint of SQL reporting patterns that are expensive or wrong on big data, with the concrete rule set GV001-GV012 enumerated. The phrase 'no database needed' immediately separates it from siblings that touch a real connection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives an explicit use case ('quick check while writing SQL') and names two alternatives with the conditions that select them: gulliver_fix for rewritten SQL, gulliver_preflight for cost on a real connection. No inference required.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, and the description reinforces the scope with 'reads the local receipt log only', which rules out live execution or remote state. It also implicitly characterizes the payload (estimates, budget verdict, approvals) beyond the safety profile, though it says nothing about retention or how far back receipts go.

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

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

Three tight sentences, front-loaded with the object of the call before the audience/format note and the trigger. Dense but every clause carries information; the middle clause about formats is the closest to redundancy given the schema already says the same.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with full schema coverage, an output schema and complete annotations, nothing an agent needs to select or invoke it is missing. The description covers what is retrievable, which sibling outputs produce receipts, and the appropriate call timing.

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

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

Schema coverage is 100% and both parameters are already documented in the schema, including the enum values, the 'latest' default and the unknown-id error behavior. The description's format guidance largely restates the schema, adding no new syntax or edge-case detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource (get the receipt) and immediately enumerates what the receipt contains: SQL, estimates, measured numbers, budget verdict, human approval. It also pins the receipt to outputs of named sibling tools (preflight, rehearse, run, diff, check), so an agent can place it precisely in the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives a concrete trigger: use it after a run when the human asks what happened or why, plus format routing (markdown for humans/PRs, json for agents). It stops short of naming an alternative sibling for the same need or stating when not to call it, so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces 'Never writes data' plus adds cost context ('budget-checked first') and an important side effect the annotations do not cover: a receipt is logged for gulliver_receipt. It also documents the growth-exponent signal for join row multiplication, which is genuinely useful behavior beyond the structured fields.

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

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

Front-loads the core action and keeps cost, safety, and routing in tight sentences; the parenthetical about default sample sizes is slightly redundant with the schema but costs little. No padding sentences overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be explained, and the description covers purpose, cost, safety, routing, and receipt side effects. Minor gaps remain around failure modes (e.g. what happens when the sample is too small or the prediction cannot be fitted) for a tool with five parameters.

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

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

Schema coverage is 100% and each parameter is fully documented, so baseline is 3. The description only restates the default fractions (1%, 3%, 10%) and adds no syntax or interpretation guidance for method, sample, or connection beyond what the schema already explains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete action chain: sample the query at small fractions, measure runtime/rows/bytes, and predict the full run with a confidence range. That is clearly distinct from gulliver_run (full execution) and gulliver_preflight (pre-check), both of which are named or implied.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives explicit triggers ('when gulliver_preflight says needs_rehearsal, or when joins or skew make the estimate unreliable') and names the sibling that routes into it, so an agent knows both when to select it and when not to.

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

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.

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.

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.

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.

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.

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.

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

Beyond the annotations it discloses the multi-state response model, that the query may not actually execute, that it is read-only by default with writes gated behind a connection-level permission, and that the preview is untrusted data whose data_warnings must be read. This is substantial behavioral context; only the pagination/size behavior of the preview is left implicit (covered by max_rows in the schema).

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

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

Front-loaded with the core action and constraint, and every clause carries information (prerequisite, return shape, fallback states, safety warning). The telegraphic fragments ('Instead of running it may answer block (...); follow next_step') are dense but readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no elaboration, and the description still summarizes them usefully. Prerequisites, gating states, write safety, and untrusted-output handling are all present, making the definition complete for a gated query-execution tool.

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

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

With 100% schema description coverage, the schema already documents sql, max_rows, connection and allow_write in detail. The description's 'Read-only SQL by default' adds only a little meaning to allow_write and says nothing about the other three parameters, so it sits at the baseline for a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run the full query') plus its scope constraint ('only inside the budget') and its return payload (row preview, totals, receipt_id). It also differentiates itself from gulliver_preflight and gulliver_rehearse by naming when those must be called instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives an explicit prerequisite ('Call gulliver_preflight first') and enumerates the non-execution outcomes (block, needs_rehearsal, needs_approval) with the routing instruction to follow next_step. An agent knows both when to call this and what to do when it declines to run.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real context beyond them: it reads only local config and the spend ledger and never queries a database, which tells the agent there is no connection latency or live state. It stops short of describing freshness or output shape, but the output schema covers the latter.

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

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

Four short sentences, each doing distinct work: payload contents, session ordering, data-source scope, and alternative routing. The most important instruction (call first) is front-loaded in the second sentence with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters, an output schema, and rich annotations, the description supplies exactly the missing pieces: what is returned, when to call it, what it does not touch, and where to go instead. Nothing needed to invoke it correctly is absent.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter meaning for the description to add or omit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and a fully enumerated resource set: connections (name, engine, read-only or writable), budget limits, and money spent today per agent. It also names a sibling it is not (gulliver_inspect), so an agent can distinguish it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives an explicit ordering instruction ('Call this first in a session') with the reason (other tools take a connection name from this list), and an explicit exclusion routing table-size questions to gulliver_inspect. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description still adds real context beyond them — the history query is budget-checked, nothing is run or changed, and savings are labeled 'exact or heuristic' rather than presented as certain. It does not mention runtime cost, pagination, or what happens when budget is exceeded, which keeps it below 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.

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

It is front-loaded with the core action and squeezed into a few dense sentences with no filler, and the usage-routing sentence comes last where it is needed. The first sentence is long and stacks five data sources in a row, which costs some readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, multi-source read-only analysis tool with an output schema covering return values, the description supplies what the schema cannot: source scope, the budget check, safety, and the alternative tools. The main omission is any hint of result scale or behavior when no history is available for the chosen source.

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

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

Schema description coverage is 100%, so the schema already carries the parameter definitions and 3 is the floor. The description adds meaning the schema does not: what 'analyze' actually produces (lint, a same-rows rewrite, saving per month) and that grouping is by query shape with literals ignored, which clarifies how 'limit' and 'rank_by' behave.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource — a workload review of the most expensive repeated queries, grouped by shape with literals ignored — and enumerates the concrete sources (receipts, pg_stat_statements, BigQuery JOBS_BY_PROJECT, Snowflake QUERY_HISTORY, file). It also explicitly separates itself from gulliver_preflight/gulliver_fix for single-query work, so an agent can route correctly without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives an explicit when-to-use rule: 'use it to find where money goes across many queries; use gulliver_preflight or gulliver_fix for one query,' naming the alternatives directly. The gap is gulliver_review, the closest-sounding sibling, which is never mentioned or differentiated, leaving some ambiguity for fleet-level review tasks.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: warnings are emitted for lossy constructs, and a preflight against the target database only happens when a connection is supplied, otherwise nothing touches a database. That conditional side effect is exactly the kind of information annotations don't convey. It stops short of 5 because it doesn't say how warnings are surfaced or whether preflight can fail the call.

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

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

Three tight sentences, capabilities front-loaded, with usage and alternative routing packed into the remainder and no filler. Slightly dense but each clause carries information the agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and full annotation coverage, the description only needs to cover capability, side effects and routing — and it does all three, including the conditional database preflight. Only the treatment of warnings (blocking vs advisory) is left unstated.

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

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

Schema description coverage is 100%, so both dialects and the connection parameter are already documented in the schema, which sets the baseline at 3. The description adds one useful constraint beyond the schema — the connection must be of the target dialect for preflight to run — plus the implicit source-dialect assumption, but it otherwise repeats information the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Translate SQL between DuckDB, Postgres, BigQuery and Snowflake') and adds the scope of what it produces ('warnings for anything that may not carry over'). It also distinguishes itself from gulliver_diff, though it doesn't differentiate from the other siblings (gulliver_lint, gulliver_preflight, gulliver_check) that an agent might confuse with a translation/safety check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives a clear trigger ('Use it for migrations between engines') plus post-call advice ('check the warnings before trusting the result') and names the alternative for row-level comparison ('use gulliver_diff to compare the rows on both engines'). The connection/no-connection branch is also spelled out, but there is no explicit when-not-to-use case, which keeps it short of a 5.

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