Get Redfin climate risk for a property

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

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing the full failure envelope: `{ available: false, reason }` with the three specific reasons, the `not_covered: ['landslide']` field surfaced on every response, and the implementation fragility ('Sourced from Redfin's server-rendered homedetails HTML (no clean stingray endpoint exists)'). It also discloses the clustering behavior (same cluster_id typically shares identical scores). Annotations are consistent — a read-only, idempotent fetch — and the description adds substantial behavioral context on top.

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 it is rigorously structured — COVERS block, DOES NOT COVER block, response-shape block, source note, input note, optimization note — and every sentence carries non-redundant information. Front-loaded with purpose and coverage before implementation details. Slightly dense, but the complexity of three risk vectors plus failure modes justifies the length.

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?

With no output schema, the description must explain return values, and it does: the `available: true` shape, the `available: false` reason enum, and the `not_covered` field. Input format, geographic context, alternatives, and performance optimization are all covered. No critical gap for an agent to call this 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 100% — the url parameter already has a clear description with an example path. The description adds only marginal reinforcement ('Pass a homedetails URL (full or path)'), mostly restating what the schema already conveys. Baseline 3 is appropriate since the schema carries the semantic load.

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?

Opens with a specific verb+resource statement ('First Street Foundation climate risk scores for a property') and then enumerates the exact coverage — flood, fire, heat with per-vector detail (factors 1–10, FEMA zones, horizons, insurance bands). It explicitly carves out what it does NOT cover (landslide), which distinguishes it from a generic 'climate risk' tool and from siblings like redfin_get_area_climate_baseline.

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?

Names concrete conditions for use ('Helene-relevant risk vector in the NC mountains market and many parts of California / the Pacific Northwest') and explicit alternatives for what it does not cover (NC Geological Survey and USGS for landslide). It also gives an efficiency directive — using cluster_id to group properties and skip redundant fetches — so an agent knows when to reuse results rather than call again.

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