Explain a change in log volume

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

With no annotations provided, the description carries the disclosure burden and does it well: it explains the wider-baseline comparison, statistical over-representation, p-value ranking, and background noise filtering. It stops short of declaring read-only status or the exact result format, but the core runtime behavior is transparent.

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 with no filler. The core action is front-loaded, usage scenarios come second, and the statistical ranking detail is last. Each 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?

For a tool with no annotations and no output schema, the description covers purpose, use cases, comparison mechanism, and noise filtering. It could be more complete by noting the exact output shape or read-only behavior, but nothing essential for invoking 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?

The input schema already documents all five parameters at 100% coverage, so the baseline is 3. The description adds useful framing by clarifying the window-vs-baseline comparison and what fields are reported, but it does not need to restate parameter-level syntax.

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: comparing a window to a wider baseline and reporting which namespaces, containers, and pods are statistically over-represented. It clearly separates this analytical spike-explanation tool from siblings like es_search or es_count by naming its purpose and 'why did logs spike' use case.

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 provides concrete when-to-use triggers: 'why did logs spike', 'what changed at 14:00', and narrowing an incident to a service before reading lines. It stops short of naming sibling alternatives or saying when not to use it, so it earns a 4 rather than a5.

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