GroundTruth - Environmental Records

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

Annotations already cover the safety profile (readOnly, idempotent, open-world, non-destructive), yet the description adds substantial context beyond them: data vintage (2025-12-31, release D25_29sep2026), per-block counting semantics, the H3-cell fallback when a point is in no FCC block, satellite listed last, and the crucial caveat that speeds are advertised maximums, not measured. This is unusually rich behavioral disclosure.

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?

Dense but front-loaded: the core identity, data source, and counting model come first, then secondary ordering and caveats, then input formats. Nearly every clause carries information, though the single-block prose could be broken into shorter sentences for faster scanning.

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 carries the return-shape burden and does so: providers, technologies, download/upload tiers in Mbps, residential vs business-only location counts, and the wired/fixed-wireless-before-satellite ordering. Input modes and data limitations are both covered, leaving nothing an agent needs 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 meaning beyond the schema by explaining that the address parameter is geocoded via the US Census geocoder and that coordinates must be US-based, though it does not state precedence if both address and lat/lon 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 verb and resource: fixed broadband availability for a US location from the FCC Broadband Data Collection, counted per 2020 Census block. The resource is unambiguous enough that an agent can distinguish it from drinking_water, environment_near, and location_scores without opening any 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?

Gives clear applicability context (US locations only, accept either a geocoded street address or lat/lon) and an important limitation ('cannot confirm service at one house'). It never names an alternative tool or states when a sibling should be preferred, so it stops short of full routing guidance.

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 read-only, idempotent, non-destructive profile, so the bar is lower, and the description still adds real behavioral context: matching is approximate because service boundaries are not public, and the authoritative source is the user's water bill. It does not cover pagination or result-size behavior, but the key caveat is disclosed.

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?

Two sentences with zero padding. The scope statement comes first and the accuracy caveat second, which is the right front-loading for a lookup tool.

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?

No output schema exists, and the description compensates by naming what comes back (SDWA violation summaries) plus the approximation caveat. Safety semantics are covered by annotations, so little is missing; only result shape/pagination detail is absent.

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 all three parameters carry their own descriptions, so the schema does the heavy lifting. The description adds the combination semantics ('state + county and/or city'), which slightly clarifies that city and county can be used independently or together, but no format or edge-case detail beyond that.

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 states a specific verb+resource (look up public water systems), the scope (a US state plus county and/or city), and the payload (health-based SDWA violation summaries). It is clearly distinct from the sibling tools due_diligence and environment_near, though it never explicitly names them.

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?

Usage is implied by the resource description, but there is no explicit when-to-use vs. when-not or any reference to the alternatives (due_diligence, environment_near). The note about the water bill points at a fallback when matching fails, which is a useful hint but not a full use-condition.

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 a safe, idempotent, read-only, open-world read, and the description adds far more: monthly snapshot staleness, per-dataset as_of provenance, US Census geocoding of addresses, and the exact negative-space limits (NPL-only Superfund, newest TRI year, current noncompliance flags only). The 'empty result does not mean the area is free of contamination' caveat is precisely the kind of behavioral framing an agent needs.

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 and data sources are front-loaded, then caveats, with essentially no filler sentences. It is a single dense block rather than clearly structured, which costs a point, but every clause carries 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?

With no output schema, the description carries the return-value burden and discharges it: each record carries date, distance, and source, and provenance supplies each dataset's snapshot date. Combined with coverage limits and empty-result semantics, nothing an agent needs to call this correctly 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 schema already documents lat, lon, address, and radius_km including defaults and bounds, making baseline 3 appropriate. The description adds only that address is geocoded by the US Census geocoder and is an alternative to lat/lon, a modest addition over 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 and resource ('Environmental records within a radius of a US location') and enumerates exactly which three EPA datasets are covered, so scope is unambiguous. It never names or contrasts the sibling tools (drinking_water, due_diligence), so it stops short of the sibling differentiation a 5 requires.

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 gives strong interpretive guidance ('Results are records, not a safety assessment', empty result semantics, and an explicit list of EPA records it does not search), which is real when-to-expect-what context. However, it offers no guidance on when to pick this tool over its obvious sibling due_diligence, leaving tool selection to 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 already cover safety (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial meaning on top: scores are model estimates not safety ratings, 0-1 with 1.0 favorable, null means unscoreable, no_coverage marks placeholder numbers, caveats.<layer> carries limits, and it explicitly warns that absence of adverse signals is not a clean bill of health. It also discloses the geocoding source and per-layer geographic coverage.

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 opening sentence is well front-loaded with the layer list, but the remainder is one dense run-on paragraph mixing caveat semantics, coverage geography, and grid references. Much of it earns its place, yet the coverage enumeration is verbose and hard to scan for an agent deciding whether to call the tool.

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 carries the full burden of explaining returns and does so thoroughly: value range, null vs no_coverage placeholders, caveats.<layer> structure, model-estimate provenance, and per-layer coverage. An agent has everything needed to interpret results 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%, so the baseline is 3, and the description adds real value beyond it: it names the US Census geocoder used for addresses and clarifies that input is either an address or lat/lon coordinates. The lon sign caveat (negative except Guam, NMI, western Aleutians) largely duplicates the schema, but the geocoder detail is genuinely new.

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 states a specific resource (layer scores for a US location) and enumerates the exact layers returned (schools, hazards, groundwater, Superfund, air, noise, walkability, crime, climate), so an agent knows precisely what it gets. It does not, however, explicitly differentiate itself from the siblings broadband_availability, drinking_water, and environment_near, which overlap on environmental layers.

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?

There is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. Usage is only implied through the extensive per-layer coverage list, which tells the agent where results will be real versus null/placeholder but leaves the routing decision to inference.

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