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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context beyond annotations: radiance is not power state, cloudy readings average ~100x brighter, absence of a row means absence of a look rather than darkness, counts are per physical site not registry row, and NASA latency means responses describe a week 1-2 weeks in the past. These are critical interpretation rules an agent could not infer from annotations or schema.

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 long but deliberately structured: it opens with the core definition, then mode-specific usage, then CRITICAL INTERPRETATION RULES in capitalized sections, then latency and sensor-independence notes. Every sentence carries necessary caveats or guidance; the length is justified by the complexity of interpreting night-lights. It is slightly dense, which prevents a 5, but it is far from bloated.

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 output schema and high interpretative complexity, the description is remarkably complete. It specifies what the response contains (site-level events or radiance rollup, plus a coverage block with newest_night and lag_days), explains event semantics, provides critical false-positive causes, and tells the agent how to frame answers relative to latency. Nothing essential for correct invocation and interpretation 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 100%, so the baseline is 3. The description adds value beyond the schema by explaining the meaning of mode values ('site-level significance events' vs 'per-facility nightly radiance rollup'), defining the event types, and clarifying that days ends at the newest data night rather than today. It reinforces the country attribution caveat and adds the physical-site counting rule, which enriches parameter understanding without repeating schema text.

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 precise definition: query NASA Black Marble night-lights (VIIRS VNP46A2, ~500 m), listing the data product, resolution, and what is sampled. It clearly distinguishes two modes ('events' vs 'radiance') and names the specific event types (went_dark_lights, surge, first_light). It also separates this tool from FIRMS/thermal sensing by stating they are independent sensors, which differentiates it from the sibling query_thermal_anomalies.

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 gives explicit when-to-use guidance with concrete example queries ('which power stations went dark last week', 'unusual lighting activity in Kuwait', 'how bright is Bandar Abbas at night'). It also provides a clear when-not-to-use: a dark pixel is not a confirmed outage and went_dark_lights is an inference, never a verdict. It explicitly instructs the agent to corroborate with FIRMS/thermal data before characterizing an outage, effectively naming the alternative sensor/tool.

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