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

With no annotations, the description carries the full burden. It discloses the response structure (evidence block with exact query, execution time, series/sample counts, warnings) and mandates citation of that evidence. It does not mention side effects, rate limits, or auth, but for a read-only query tool this covers the most important behavioral aspects.

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 two sentences with zero fluff. It front-loads the core purpose ('Run an instant PromQL query') and then adds the critical response/citation detail. Every word earns its place.

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 there is no output schema, the description explains the response's key components (evidence block) and the mandatory citation behavior. It also covers the instant evaluation nature. It omits potential error handling or edge cases, but for a straightforward query tool this is sufficient for an agent to call it correctly.

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 both parameters (promql and time) are already documented. The description does not add parameter-specific detail beyond the schema, which is acceptable; the baseline of 3 applies.

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 an instant PromQL query, specifying the verb 'run' and the resource 'PromQL query'. The word 'instant' distinguishes it from likely time-range siblings like range_query, though it does not explicitly name them, so it's not a perfect 5.

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 the tool is for point-in-time queries via the word 'instant', but it does not explicitly state when to use this tool versus alternatives like range_query or list_metrics. There is no direct comparison or exclusion of sibling tools, leaving some inference to the agent.

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

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

No annotations are provided, so the description carries the burden. It discloses the read-only nature implicitly ('List') and the substring filter behavior, but doesn't state whether the list is exhaustive, paginated, or limited in any way. For a simple read-only listing tool, this is adequate but not rich.

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, zero waste. The core action and filter are front-loaded, and the usage guidance is a single actionable sentence. Every word earns its place.

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 simple single-parameter listing tool with no output schema, the description covers the action, the filter, and the use case. It doesn't describe the return format, but for a list of metric names that's a minor gap given the tool's simplicity.

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 the 'contains' parameter as an optional case-insensitive substring filter. The description adds the purpose context (verifying metric existence) but no additional parameter-level detail beyond the schema.

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 ('List') and resource ('metric names known to this Prometheus'), and adds the optional substring filter. It clearly distinguishes itself from siblings like instant_query and range_query, which execute queries rather than enumerate metric names.

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 explicitly tells the agent when to use this tool: to verify a metric actually exists before concluding anything from an empty query result. This is clear usage guidance that also implies when not to use it (when you need actual values, use instant_query or range_query instead).

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

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.

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

No annotations exist, so the description carries the behavioral burden. It discloses that a down target 'silently turns into missing data everywhere else' and ties tool output to query trustworthiness. It could mention read-only/no-side-effect behavior explicitly, but 'summarize' strongly implies it.

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, both purposeful: the first states what the tool returns, the second states when and why to call it. No filler or 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 parameterless, simple summary tool, the description fully covers what it does, what it returns, and when to use it. No output schema is needed because the return shape is stated in plain language.

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 tool has zero parameters, so there is no parameter information the description must add. The baseline for zero-parameter tools is 4, and the description appropriately focuses on output and usage rather than padding.

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 uses a specific verb ('Summarize') and names a precise resource ('scrape target health') with the exact output ('up/down counts per job'). It clearly stands apart from sibling query/list tools by focusing on health rather than data retrieval.

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 explicit situational guidance: 'Check this first during an incident' and explains why. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent can decide when this tool is the right first step.

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