assess_location_hazard

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

With no annotations, the description must carry full behavioral disclosure. It explains the internal pipeline (geocoding, discovery, filtering, modeling) and return format, and lists method references. Yet it omits key operational traits like requiring pre-configured credentials (a configure_credentials sibling exists), potential latency or rate limits, and whether large data downloads occur, leaving gaps for a complex tool.

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 well-organized: purpose paragraph, args list, returns section, and references. It front-loads the aggregating purpose and then details each parameter, which is appropriate given the tool's complexity and 0% schema coverage. The references section adds scientific credibility but is arguably non-essential for invocation, making it slightly verbose.

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?

Given the tool's 8 parameters, no annotations, and an output schema, the description covers the parameter set thoroughly, provides examples, and states return format. Missing are prerequisites like 'configure_credentials must be called first' and potential error behavior, which would elevate it to a 5. Overall it is nearly complete for a turnkey analytical tool.

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 is the only source. It documents all 8 parameters, including location format examples, an enumerated list of hazard_type values not present in the schema, datetime_range format, output format enum, defaults for water_level_rise_m/storm_surge_m, IPCC scenario presets, and the days lookback default. This makes the tool callable without external docs.

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 declares an 'Ergonomic All-in-One Planetary Hazard Assessment' that bundles geocoding, STAC discovery, scene filtering, and specialized hazard modeling into a single call. This clearly distinguishes it from specialized siblings like simulate_sea_level_rise or analyze_coastal_erosion, and the verb 'assess' plus resource (location/hazard) is explicit.

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 states the tool 'Replaces 4-6 manual tool calls' and bundles geocoding, STAC discovery, filtering, and modeling, which strongly implies use when a complete end-to-end hazard assessment is needed. However, it does not explicitly name sibling specialized tools or state when to prefer them instead, so the guidance is contextual but not exhaustive.

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