Impala Query Ranking

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

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses default filtering (only QUERY/DML and failures unless include_ddl=true), that 'score' only considers queries with problems, that 'spill' only returns queries that actually spilled, and that thresholds like slow_seconds, memory_gb_per_node, and planning_seconds are configurable with stated defaults. It also documents the CM filter syntax with an example. It does not state read-only semantics or cost/limit behavior explicitly, 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?

The description states the purpose up front, then moves to the rank_by modes and finally to the filters and thresholds, with each parameter explained in one compact line. The rank_by block is inherently long because of the five modes, but each mode earns its place. Little is wasted, though the density borders on a schema restatement.

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 needn't be described, and the description covers the semantic model (problem ranking, per-query motive) well. For a 14-parameter tool with zero schema description coverage, though, leaving top, max_queries, service, and cluster undocumented is a real gap, since an agent cannot infer that top caps the result list or that max_queries bounds the scan.

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 must compensate, and it covers rank_by (fully, mode by mode), hours, user, pool, database, include_ddl, extra_filter, slow_seconds, memory_gb_per_node, and planning_seconds. It never explains top (result count), max_queries (scan cap), service, or cluster, and those are consequential parameters for a 14-parameter tool. Coverage is good but incomplete on high-impact knobs.

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: ranking of problematic Impala queries within a window, with the reason for each. It also frames the output by explaining that each ranking is justified by a motive. It doesn't explicitly contrast itself with siblings like impala_query_details or impala_query_issues_summary, but the framing is distinctive enough that an agent can distinguish it from generic detail or summary tools.

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 rank_by enumeration effectively implies when to use each mode: 'memory' for OOM, 'spill' for disk pressure, 'planning' for statistics/admission failures, and 'duration' for slow queries. However, there is no explicit statement about when to use this tool rather than impala_query_issues_summary or impala_query_details, and there are no prerequisites or exclusion guidance. As a result, usage guidance is implied, not stated.

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