storage_capacity_rca

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

With only readOnlyHint declared in annotations, the description carries the behavioral load well: it discloses severity rules, that warning-or-worse events naming a domain get attached, that unattached domains are skipped, and the edge case where unset thresholds (engine reports 0) are reported low. These are substantive traits beyond the annotation.

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 core purpose is front-loaded, which is good, but the severity discussion is dense and some sentences (e.g., the 'nothing — not the engine, not this tool — will warn' clause) are convoluted and could be tightened. Roughly adequate but with clear verbosity.

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?

There is no output schema, so the description must explain what findings look like — and it does, covering rank ordering, quoting signals, severity semantics, skipped domains, and the unset-threshold edge case. For a complex RCA tool this is complete enough to invoke and interpret 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 0%, but the Args block fully compensates: events_limit 1-1000 (default 200), events_window_hours 1-720 (default 24), and target (engine target name from config, omit for default). All three parameters get meaning, bounds, and defaults that the bare schema lacks.

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 and resource: storage-domain problems ranked worst-first in a single call, explicitly tagged [READ]. This is clearly distinguishable from storage_domain_list/get (raw listing) and engine_health_rca (different domain), so an agent can select it without opening the schema.

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 rich interpretive guidance — severity mapping (critical below free-space blocker, medium below low-space warning, high for inactive/unknown/mixed domains) and exclusions (unattached domains are skipped; over-commit alone is not a space shortage). It lacks any explicit routing to a sibling alternative, keeping it short of a 5.

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