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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description reinforces with 'Read-only: it never writes to or mutates Loki' and adds the raw return format ('{"status","data":["label","names"]}') plus the behavior about only labels present on streams with data in the window. This goes beyond the annotations.

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?

Three sentences front-load the purpose, then explain the workflow and return format. Every sentence earns its place, with no redundancy or filler.

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 read-only list tool with two optional parameters and no output schema, the description fully explains purpose, usage context, return format, and operational behavior. Nothing an agent needs to call it correctly is missing.

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 coverage is 100% (start and end documented with types, defaults, and format). The description adds the insight that widening start/end surfaces more labels, which is extra semantic value beyond the schema, but the core semantics are already covered.

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 verb 'List' the resource 'label names' within 'Loki' and a time window. It differentiates itself from siblings by explicitly contrasting with label_values and query_range, and positioning itself as the starting point for schema discovery.

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 directs the agent: 'Start here when the log schema is unknown' and describes the sequence labels → label_values → query_range. It also gives a practical tip about widening start/end to surface more labels, making the intended use unambiguous.

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 the raw JSON response format, the empty-list behavior for unknown labels, and explicitly states 'Read-only: it never writes to or mutates Loki.' This adds behavioral context beyond the annotations (readOnlyHint, destructiveHint, idempotentHint) by clarifying exact response shape and error behavior.

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 about 70 words, front-loaded with the core action, then logically flows into usage, behavior, and return format. Every sentence carries useful information, with 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?

It covers purpose, usage pattern, response format, edge cases (unknown label), read-only guarantee, and parameter interpretation. The presence of annotations and sibling context fills remaining gaps, making this fully self-sufficient for an agent.

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?

Although the schema covers 100% of parameters, the description adds significant meaning: it ties start/end to the time-window semantics, gives an example ('app') for the label pattern, and explains the default values. This elevates the parameters from syntax to usage.

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 starts with a clear, specific verb and resource ('List the values a single label takes in Loki over a time window') and immediately distinguishes it from siblings by explaining when to use it (after labels, before query_range). It names the exact context and how it fits the workflow.

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?

It explicitly states when to use this tool: 'Use it after labels to fill in a selector' and walks through a concrete example (labels says 'app' exists, label_values gives actual values, one goes into query_range). It also notes the effect of widening start/end, giving clear guidance on parameter usage.

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?

Annotations already declare read-only and idempotent, but the description adds the exact return format (raw Loki JSON with resultType 'vector' or 'streams') and explicitly states 'never writes to or mutates Loki'. This goes beyond annotations by specifying output structure and result semantics.

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?

Compact and well-structured: core action first, then usage guidance, then return format, and finally safety. No filler; every sentence 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?

Without an output schema, the description fully explains the return JSON and resultType. It also covers usage context, parameter guidance, and safety. For a read-only query tool, nothing essential is missing.

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 coverage is 100%, meeting the baseline, but the description adds value by explaining how the query parameter should be shaped (metric examples like rate, count_over_time) and clarifying that limit applies only to log selectors (though this is also in schema). The description reinforces parameter behavior without redundancy.

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?

Clearly states the tool runs a LogQL instant query against Loki, evaluates at a single point in time, and differentiates from query_range (time window) and labels/label_values (label discovery). The verb 'run' and resource 'Loki' are specific and unambiguous.

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 states when to use (metric expressions needing one value per series, quick 'what is happening right now' checks) and when not (query_range for time ranges, labels/label_values for label discovery). Names alternatives and conditions clearly.

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?

Annotations already cover readOnlyHint, destructiveHint, idempotentHint. Description adds valuable behavior beyond those: truncation at limit with advice to narrow range, direction effect ('With backward and a hit limit, you keep the newest entries'), and explicit read-only statement. No contradiction; it enriches transparency with operational details.

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?

Well-structured: purpose first, then usage guidance, then output format, then truncation caveat, then read-only note. Every sentence delivers distinct value—no filler. Front-loaded with the most important usage context. Appropriate length for a complex tool.

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 no output schema and complex behavior, the description explains the raw JSON response format, resultType meanings, truncation behavior, and parameter interactions. It also covers edge cases (metric expressions ignore limit, direction defaults). All necessary information for correct invocation is present.

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 baseline is 3. Description adds nuance: clarifies that limit applies only to log selectors (not metric expressions), explains direction's effect on truncation, and advises narrowing start/end rather than raising limit. This goes beyond schema's per-parameter descriptions, adding operational semantics.

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?

Description states a specific verb ('Run a LogQL range query'), resource ('Loki'), and scope ('across a time window'). It explicitly distinguishes from sibling 'query' (point-in-time) and mentions 'labels' and 'label_values' as alternate tools. An agent can immediately understand what this tool does and how it differs from siblings.

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?

Provides explicit guidance: 'This is the tool to reach for when reading logs' and gives concrete scenarios (searching errors, tailing over an hour, graphing metrics). It specifies when to use 'query' instead and instructs to call 'labels' and 'label_values' first if selector unknown. Clear when/when-not with named alternatives.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety is covered. The description adds valuable context beyond annotations: the exact return shape (raw Loki JSON with status/data), the empty-list behavior for no matches, and a concrete example of selector expansion. It also repeats the read-only guarantee, reinforcing but not contradicting the annotations.

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 compact yet thorough, leading with the core action, then purpose, usage guidance, return format, and safety note. Every sentence adds new information—no redundant fluff. The alternative-tool routing is front-loaded and the response format is clearly specified up front, making it easy to scan.

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 tool with three parameters and no output schema, the description is exceptionally complete. It covers the raw JSON structure, empty-list case, read-only nature, selector expansion, and explicitly routes to sibling tools. Time range defaults are in the schema, and the description complements rather than duplicates, leaving nothing essential missing 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?

The schema covers all three parameters at 100% with clear descriptions, including the match selector syntax and time range defaults. The description adds significant extra semantic value by explaining the expansion behavior ('{app="nginx"} may expand to one series per pod, region or level'), which directly illuminates how the match parameter behaves in practice, beyond a simple field description.

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 ('List the log streams matching a selector') and immediately clarifies it returns complete label sets. It explicitly differentiates from siblings by naming query_range, labels, and label_values as alternatives for different purposes, making the tool's unique role unmistakable.

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 states exactly when to use this tool ('to see which concrete streams a selector actually covers', 'does this selector match anything', 'how many streams am I about to read') and gives explicit exclusions: 'For the lines themselves, use query_range; for label names and values in isolation, use labels and label_values.' This leaves no ambiguity about when to choose this tool over siblings.

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