loki_query

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

Beyond the readOnlyHint annotation, it discloses real operational behavior: the stream-selector validation gate, a capped lookback, a clamped line limit, and truncation semantics with the recommended remediation. That is exactly the extra context annotations cannot carry.

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?

Front-loaded with purpose, then Args, then Returns in clearly labeled blocks; no sentence is filler. The truncation caveat is placed where an agent will act on it.

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?

With no output schema, the description supplies the return envelope (returned/limit/truncated) and interprets the truncated flag, and it covers every input parameter plus the hard validation constraint. Nothing needed to invoke or interpret the call 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 description coverage is 0%, so the description carries the whole burden — and it does: logql (with a concrete example and the selector requirement), hours (lookback, capped), limit (max lines, clamped), and target (config name, omit for default). All four parameters are explained with meaning beyond their names.

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 opening line states a specific verb and resource — a bounded LogQL query_range passthrough — plus the two distinguishing traits (validation-gated, bounded). It is immediately separable from siblings like loki_tail_errors or log_volume_analysis, which are curated analyses rather than a raw query passthrough.

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 gives the gating condition (a stream selector is mandatory; unbounded queries are rejected) and follow-up guidance (re-run with a higher limit when truncated). It does not, however, name when to prefer this over sibling log tools or state any exclusions, so it stops short of full when/when-not guidance.

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