US Flood Zone & Property Risk (FEMA, NOAA, USGS, Census)

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial non-obvious behavior: the flood zone is required and a failed FEMA read aborts the call with no charge, other sections degrade to 'unavailable', every section carries a status, and billing is 8c as property.address_profile. This is exactly the added context the annotations cannot provide.

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?

Purpose is front-loaded in the first sentence and the section list is scannable, but the bullet enumeration of report sections partially duplicates the output schema and could be trimmed. Still, every block carries selection or invocation value rather than filler.

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?

An output schema exists so return shape needn't be restated, yet the description re-lists the sections; the genuinely load-bearing additions (failure semantics, billing, disclaimer retention, sources[]) are present. The main gap is that the mutual exclusivity of address vs lat/lon is never resolved for an agent.

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 coverage is 33% (only `address` is described) and none of the three params are annotated in the description beyond implying 'address or coordinate'. It does not explain coordinate format, whether address is geocoded server-side, or how lat/lon and address interact when both or neither are supplied despite 0 required params.

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?

States a specific verb+resource and scope: a 'one-call US property report for an address or coordinate' enumerating flood, demographics and hazards. It explicitly distinguishes itself from the siblings flood_zone, hazard_history and area_demographics, so an agent can route without opening a 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?

Has an explicit 'When to use' clause: use for an overview of a US property rather than one specific fact, and it names the three sibling tools it replaces. It also implies when-not by positioning itself against single-fact tools.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds real operational context: no provider call, TIGER/Line sourcing, most-specific-first ordering, and the genuine county-line edge case returning two rows with advice to take the first.

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?

Front-loaded with the one-line answer and organized with a labeled 'When to use' block and edge-case note. Slightly redundant: freeness is stated twice ('Free - answered from boundaries...' and 'This tool is free and does not consume plan credits').

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?

An output schema exists so return values need no explanation, yet the description still usefully notes ordering, the dual-county case, and the sources[] licence array. For a two-parameter lookup with full annotation coverage, nothing an agent needs 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 0%, so the description technically carries the burden, but it only says 'a coordinate' without restating the lat/lon ordering or bounds already enforced by the schema's min/max constraints. The parameter names are fully self-documenting, so nothing is genuinely ambiguous, but the description adds no meaning beyond the schema.

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?

States a specific verb+resource ('State and county for a coordinate') plus the key output artifact (Census GEOIDs), and the point-in-polygon framing implicitly separates it from address-based siblings like census_geocode. An agent can tell what it produces 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?

Explicit 'When to use' guidance tells the agent to call this before any census-keyed request and notes it is free so there is no reason to guess a FIPS code. It does not explicitly name a sibling alternative (e.g. census_geocode for addresses), so the when-not is left implicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantive behavior: values are survey ESTIMATES with margins of error, suppressed estimates return null rather than being imputed, provenance lives in dataset_version/period, and every response carries a sources[] array with licence. It also discloses billing at 1c.

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?

Front-loaded with the output in the first sentence, then composition, caveats, usage, billing, and provenance in scannable chunks — every section does work. Slightly padded by the internal spec reference (§22.2) and the standalone billing/sources lines, which cost a little tightness.

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?

An output schema exists, so return shape need not be spelled out, and the description still volunteers the estimate/null semantics and provenance fields an agent would otherwise misread. Given the composition of two datasets and the zero-required-parameter signature, nothing needed for correct invocation 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 only 33% (lat/lon carry no descriptions), so the description must carry weight. It clarifies that lat/lon form a point coordinate and that geoid is a 5-digit county key that bypasses the boundary lookup, which is real value. It stops short of stating pairwise/single-input requirements or the lat/lon unit conventions.

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?

States a specific verb+resource+scope: population and median household income for the county containing a point, from ACS 5-year estimates. It also names the pipeline (TIGER/Line GEOID resolution then ACS read), which separates it from census_geocode and admin_areas without opening a 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?

An explicit 'When to use' line gives the user-intent phrasing ("how many people live in this area") and routes the agent: supply a coordinate, or reuse a county GEOID from the sibling tool admin_areas. The geoid-passthrough condition is stated with its consequence (skips the boundary lookup).

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, but the description adds substantive behavior: cost (free, no plan credits), failure semantics ('reported as not found, never guessed'), coverage limits (US only; PO boxes and rural routes often fail), and a sources[] array in every response. That is real context beyond the structured fields.

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?

Well front-loaded: the core transformation is in sentence one and constraints follow. It is somewhat bloated for a one-parameter tool, repeating the free/no-credits claim three times across separate sentences, which is wasted space.

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?

An output schema exists, so return-value detail is unnecessary, yet the description still flags the sources[] element. Combined with cost, failure behavior and geographic limits, an agent has everything needed 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 coverage is 100% and the single address parameter is already documented with an example, so baseline is 3. The description adds real constraint meaning for that parameter — US-only scope and PO-box/rural-route non-match behavior — which helps the agent predict failures, though it gives no syntax or normalization guidance.

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?

States a specific verb and resource ('turns a US street address into a latitude/longitude plus the state, county and census tract ... with GEOIDs') and names the mechanism (U.S. Census Bureau geocoder). It clearly separates itself from siblings by noting that flood_zone, hazard_history and address_profile also accept addresses directly.

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?

Gives explicit sequencing ('Use it first, then pass the point to the paid property tools') and an explicit when-not: 'call this only when the user wants the location itself.' Alternatives are named, so the agent can route correctly without inference.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive, open-world), and the description adds substantial context beyond them: 30-day caching, Census geocoding with the returned point, ambiguous addresses refused with candidates, unmapped vs. low-risk distinction, outside-US not-found-and-not-charged handling, higher-risk zone on boundaries, 2c billing, and the mandatory disclaimer.

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 lede sentence is well front-loaded and answers the question immediately, but the body is long and repeats itself — 'Live from FEMA's National Flood Hazard Layer' and 'whether it is in the Special Flood Hazard Area' each appear twice, and the second paragraph re-lists fields already given in the first.

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?

An output schema exists, so return values need not be explained, yet the description still covers the operational facts an agent needs: cost, caching, disclaimer obligations, geocoding path, and every edge case (unmapped, unmapped-but-not-low-risk, outside US, boundary ties). Nothing material is missing for a 3-param, no-required-param 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the address is geocoded with the Census Bureau geocoder, the resolved point is returned, and an ambiguous address is refused with its candidates rather than silently resolved. It confirms address and lat/lon are alternatives but does not spell out what happens if both or neither are supplied.

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?

States a specific resource (FEMA flood zone for a US address or coordinate) and enumerates exactly what is returned: zone, SFHA membership, base flood elevation with datum, FIRM panel and date, NFIP community, LOMR. It also names the sibling it is not (address_profile), so an agent can route without opening either 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?

Has an explicit 'When to use' block covering the triggering questions (in a flood zone, needs flood insurance, in the SFHA or floodway) and names the alternative tool address_profile plus the condition for choosing it. The 'not an official determination / not an elevation certificate' exclusion is stated too.

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

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

Far beyond the annotations, it discloses per-section status, graceful degradation when one source is down, that the call fails and is not charged when both FEMA and NOAA fail, the 2c billing key, the Connecticut planning-region gap, NOAA's reporting lag, and that shared forecast zones are split into `zone_based`. It also clarifies that unreported damage is treated as a floor rather than a true zero.

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 one-line summary is front-loaded and the three bulleted source blocks make the length scannable rather than rambling. It is on the long side and repeats some scoping details (geoid/GEOID handling) in two places, but each section carries operational 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?

For a multi-source aggregation tool the description covers input mutual exclusion, partial-failure semantics, edge cases (non-county GEOID, Connecticut regions), scoring/billing, and the sources[] provenance array. With an output schema present, no return-value documentation is needed.

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 60% schema coverage, the description usefully adds precedence rules the schema does not state: `geoid` is used only when no address or coordinate is supplied, and the earthquake section is skipped when only a GEOID is given. It also clarifies `years` as full years back from 1 January plus the current year, though lat/lon semantics (search radius) stay implicit.

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 sentence names the resource (natural-hazard history), the scope (US county or address) and the three concrete data sources (FEMA declarations, NOAA storm events, USGS earthquakes) with their filters. It is immediately distinguishable from siblings like flood_zone and address_profile, which are explicitly named later.

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?

An explicit 'When to use' block enumerates the triggering questions (floods/hurricanes/earthquakes, disaster declarations, storm damage history, due diligence) and names the two alternatives with the condition that selects each. Nothing about tool selection is left to inference.

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