describe_engine_capabilities

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

Annotations already establish the tool as read-only and open-world, so the description is free to add value. It does so by disclosing that the output distinguishes exact vs. approximate cost signals and that this affects interpretation of downstream accuracy_tier values.

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 tightly scoped sentences, with the core purpose front-loaded and the usage guidance immediately following. No filler or repetition of schema details.

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 the single enum parameter, the output schema presence, and annotations indicating a safe read operation, the description covers everything needed: what it does, when to use it, and how to interpret its result in context.

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 single parameter engine is clearly identified as the warehouse engine, and its enum values are self-describing. The description adds little beyond the schema, but for a one-parameter enum this is not a meaningful 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?

States a specific verb and resource: declaring which cost signals are exact vs. approximate for a warehouse engine. It clearly differentiates itself from siblings like estimate_query_cost and run_query_bounded by framing itself as a prerequisite capability 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?

Explicitly instructs the agent to call this before estimate_query_cost or run_query_bounded, and explains why: to calibrate trust in accuracy_tier. It does not explicitly state a when-not case, but the sequencing guidance is clear and actionable enough.

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