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

Beyond annotations (read-only, idempotent, non-destructive), the description discloses material behavioral facts: the index was 'WITHDRAWN 2026-08-08, RESTORED 2026-08-30' after defect repairs, old figures are not comparable, and unpriced states return 'verdict UNSCORED with dcgi null and an `unscored_reaon` — absence, not a low score.' It also names the output field `gas_price_series` and where methodology corrections live. This is exactly the kind of context annotations cannot express.

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 dense with audit history, star bullets, and repeated withdrawal-and-restoration warnings: 'Withdrawn 2026-08-08, restored 2026-08-30' and 'do NOT compare' appear multiple times across the description and parameter text. The first sentence earns its place, but the detailed three-term defect narrative and duplicated caveats could be cut by more than half without losing information.

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?

Annotations and output schema cover safety and return structure, and the description adds genuine caveats (unpriced verdicts, non-comparable vintages, alternative tool). However, both parameters are optional and the description never states what happens when `state` is omitted or what the default limit actually is, leaving a real calling gap.

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?

With 100% schema coverage, the baseline is 3; the `state` parameter description goes further by explaining the return verdict, `gas_price_series`, the `unscored_reaon` absence semantics, the corrected-index warning, and a sibling pointer. `limit` remains generic ('default varies by tool'), so not every parameter is enriched.

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 clause defines the tool as 'Data Center Gas Index (DCGI) — the per-US-state natural-gas suitability score,' which gives a concrete resource and scope. It stops short of an explicit action verb such as 'returns' or 'fetches,' and the correction-history text dilutes the clarity, so it does not reach 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 ends with an explicit routing instruction: 'Use get_gas_intelligence for the per-state pipeline and operator brief,' which names a sibling and its purpose. It does not provide broader when/when-not conditions or distinguish among the many energy-related sibling tools, so it is a useful pointer rather than full selection guidance.

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