Explain why a Rego query is undefined

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

The description goes well beyond the annotations, revealing the internal strategy (plain eval + full-trace eval + per-condition AST analysis), the two handled failure modes (runtime failures and indexer elimination), the behavior for default rules (`queryResult` reports `default`), and the return shape (structured breakdown plus human-readable summary). Annotations already mark it read-only and idempotent, and nothing in the description contradicts them.

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 front-loaded with the core purpose, then explains the method, the default-rule edge case, and finally the return value. Every sentence contributes useful context, though the technical method details and the restatement of the 'why is allow false' question add slight extra length. Overall it remains well-structured and 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?

The description covers the critical information an agent needs: query format, diagnostic behavior, special handling of default rules, and output contents, which matters because no output schema exists. It does not explicitly discuss the input/inputPath/paths/source parameters, but the schema fully describes those with 100% coverage, so this is not a significant gap.

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 each parameter is already documented with meaningful detail. The tool description adds minimal parameter-specific information beyond the fully-qualified query concept, so the baseline score of 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?

The description opens with a specific verb and resource: 'Diagnose why a fully-qualified Rego query ... produces no value, or falls back to its default.' It clearly distinguishes this diagnostic tool from eval/explain siblings by describing the combined methodology (plain eval, full-trace eval, per-condition AST analysis) and explicitly addressing the default-rule case.

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?

The description gives clear context for when to use the tool: when a fully-qualified Rego query is undefined or falls back to a default, and explicitly frames the question 'why is allow false' as the target. It does not explicitly name alternatives or state when not to use it, but the diagnostic intent is evident and the query path requirement is reinforced by the schema.

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