estimate_query_cost

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

Annotations already indicate readOnlyHint, but the description goes well beyond by explaining the accuracy_tier semantics (PRECISE, UPPER_BOUND, HEURISTIC) and the impact of warehouse_size/edition defaults on cost understatement. This adds valuable behavioral context that annotations alone do not provide, such as the trustworthiness of the returned number and how to get a more accurate estimate.

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 description is relatively long but every sentence earns its place: purpose and usage directive are front-loaded, followed by the accuracy tiers, then the optional-parameter caveat. It is well-structured and information-dense without redundancy.

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 cost-estimation tool with an output schema, the description covers all aspects an agent needs: what to pass, accuracy tiers (likely an output field), and how to tune inputs for a reliable estimate. There are no obvious gaps in calling it correctly; even error conditions are implicitly covered by the accuracy-tier guidance.

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 0%, so the description carries the full burden for parameters. It explicitly explains warehouse_size (engine-specific) and edition (engine-specific), their defaults, and the consequences of omission (understated cost). It also ties engine to available tiers. This fully compensates for the schema gap, leaving no parameter unaddressed beyond the obvious sql and engine.

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 states a specific verb ('Estimate') and resource ('cost of a SQL query'), and clearly frames it as a pre-run estimation. It distinguishes itself from siblings like run_query_bounded (which likely executes) and check_credentials (credential verification) by being strictly an estimation tool. No ambiguity.

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 explicitly says 'ALWAYS call this before running an expensive-looking query', which is a clear directive for when to use. However, it does not mention when not to use or explicitly reference alternatives like run_query_bounded. It gives strong context but lacks the 'when-not' and alternative naming, so a 4 is appropriate.

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