range_query

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

The description discloses a key behavioral trait: the response includes an evidence block with sample coverage, and if samples per series are low, the evidence will say trends are unreliable, and that warning must be surfaced to the user. This goes beyond the schema and annotations (which are absent), providing actionable behavioral context about output interpretation and user-facing obligations.

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 sentences with no waste. The core action is front-loaded, and the critical behavioral warning about sample coverage is included without padding.

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 core action and the most important output behavior (evidence block, sample coverage warning). It doesn't mention pagination, limits, or error cases, but for a query tool with a clear schema and no output schema, the essential context is present. The warning about surfacing unreliable trends is a valuable addition.

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 documents all four parameters. The description adds context about the time window and evidence block but doesn't add parameter-specific semantics beyond what the schema provides. 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?

The description clearly states the tool runs a PromQL range query over a time window, which is a specific verb+resource combination. It distinguishes itself from instant_query (a point-in-time query) by explicitly mentioning 'range query over a time window'.

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 implies usage for time-bounded PromQL queries and mentions the evidence block behavior, but it doesn't explicitly state when to use this vs instant_query or list_metrics. The sibling names provide context, but the description itself doesn't name alternatives or exclusions.

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