EPA drinking water data: 434,757 public water systems, violations, lead & copper, PFAS. No key.
Scored across 9 tools
The aggregate tools (state vs county summary), vacabulary-wide lists (contaminants, PFAS detections), and single-system tools are clearly separated, and descriptions explicitly point to the correct sibling tool. The only overlap is get_water_system, which bundles a latest lead/copper result and PFAS summary already served in depth by get_system_lead_copper and get_system_pfas; the descriptions call this out, so misselection risk is low but present.
All nine tools use snake_case with a predictable verb_noun shape (get_*, list_*, search_*). Minor drift in the single-system family: get_water_system is named differently from get_system_lead_copper and get_system_pfas, which would be more consistent as get_system_profile.
Nine tools is well within the sweet spot and each maps to a distinct query pattern: two geographic rollups, three single-system detail levels, two cross-cutting rankings, one list of violations, one name search. No tool feels like filler or a duplicate of another's exact purpose.
The surface covers the core read path end to end: find a system, profile it, drill into violations, lead/copper history, and PFAS, plus state/county rollups and national contaminant/PFAS rankings. Gaps are around discovery and history — no address/ZIP lookup, no geographic radius search, and violations are limited to current health-based ones with no historical or monitoring/reporting records — but agents can work around these by name/state search.
Summarize public water systems serving a US county: how many systems (and how many active), total population served, how many systems have current health-based violations and how many such violations are open, plus the worst-affected systems in the county. County names are as reported to SDWIS (uppercase). A county summary covers every system serving any part of the county; it is not a verdict on the water system at a specific address.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | Two-letter state code, e.g. IL | |
| county | Yes | County name, e.g. COOK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a read-only, closed-world, non-destructive read, so the bar is lower; the description still adds real semantic context about aggregation breadth and the interpretive limit of the result. It gives no info on pagination or response shape (which matters since there is no output schema), keeping it below a 5.
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 core purpose, followed by the metric list and then two scoping caveats. Dense but every clause carries information; the metric enumeration sentence is long but justified because no output schema exists.
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 correctly compensates by enumerating the summary contents (counts, active count, population, health-based violations, worst-affected systems). Only gap is any hint about result format or whether zero-system counties return empty vs error.
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% with examples (IL, COOK), so baseline is 3; the description adds the non-obvious constraint that county names must be uppercase as reported to SDWIS, which prevents a common lookup failure. State parameter gets no extra guidance but the schema example suffices.
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 ("Summarize public water systems serving a US county") and enumerates exactly which metrics are returned (system counts, population served, violation counts, worst-affected systems). This clearly distinguishes it from get_state_water_summary and get_water_system by scope.
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?
Explicitly bounds scope: a county summary covers every system serving any part of the county and is "not a verdict on the water system at a specific address" – implicitly routing address-specific questions to get_water_system. It does not name sibling tools directly or state when to prefer get_state_water_summary instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List current (unresolved) health-based drinking water violations from EPA SDWIS: maximum contaminant level (MCL), maximum residual disinfectant level (MRDL), and treatment-technique violations whose status is Unaddressed or Addressed. Monitoring and reporting violations are excluded. Filter by state, by PWSID, or by contaminant code; most recent compliance periods first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 50, max 500) | |
| pwsid | No | Only this system's violations | |
| state | No | Two-letter state code, e.g. IL | |
| contaminant_code | No | SDWIS contaminant code, e.g. 1040 (nitrate) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavior beyond them: the exact status filter (Unaddressed or Addressed), the exclusion of monitoring/reporting violations, and the result ordering (most recent compliance periods first). It does not describe return fields or pagination behavior beyond what the limit parameter covers.
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, densely packed, with the defining scope (current, unresolved, health-based) front-loaded before inclusions, exclusions, and filters. No clause is 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?
For a low-risk read with no required parameters and full schema coverage, the description covers scope, exclusions, filters, and ordering. With no output schema present, it could say more about what a returned violation record contains, which is the main remaining gap.
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 all four parameters are already documented in the schema, including the limit cap and an example contaminant code. The description only restates the filter axes and adds the ordering guarantee, which sits at the baseline for a fully documented 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 (List) and a precisely scoped resource: unresolved health-based SDWIS violations, enumerating the included types (MCL, MRDL, treatment-technique) and explicitly excluding monitoring/reporting violations. That scope statement distinguishes it from siblings like list_contaminants_with_violations and get_state_water_summary without needing the schemas.
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?
Clearly describes when this tool applies (current, unresolved, health-based only) and what is out of scope, and it names the three supported filter axes plus the default ordering. It stops short of naming a sibling alternative for monitoring/reporting violations, so the routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize public water systems for a whole US state: how many systems (and how many active), total population served, how many systems have current health-based violations and how many such violations are open, the counties with the most affected systems, and the state's UCMR5 PFAS sampling coverage (systems sampled, systems with detections). Data is EPA SDWIS (2026 Q3 snapshot). Use get_county_water_summary instead for one county, and search_water_systems to find individual systems in the state.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | Two-letter state code, e.g. IL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the data provenance and vintage (EPA SDWIS, 2026 Q3 snapshot) and the aggregation scope, which tells the agent results are a point-in-time rollup rather than live data. It does not discuss pagination or result size, but for a single-state aggregate that is a minor gap.
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 metric list is front-loaded and every clause names a distinct returned field, so the length is largely earned. The single long sentence is dense but readable; a bulleted or split structure would scan slightly faster.
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?
There is no output schema, so the description carries the burden of describing return values, and it does so thoroughly by enumerating each aggregate metric. Combined with the data source and the sibling routing, an agent has everything needed to select and call this tool 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 parameter already documents the two-letter state code format. The description reinforces the state-level scope ('a whole US state') but adds no format or validation detail beyond the schema, so the baseline 3 applies.
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 (summarize) and resource (public water systems for a whole US state), then enumerates the exact metrics returned: system counts, population served, health-based violations, top counties, and UCMR5 PFAS coverage. This is clearly distinguishable from the county-level and per-system siblings.
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?
Explicitly routes the agent: 'Use get_county_water_summary instead for one county, and search_water_systems to find individual systems in the state.' Both the alternative and the selecting condition are named, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lead and copper results for one water system by PWSID: the 90th percentile of tap samples for every reported Lead and Copper Rule monitoring period (latest first), with the lead action level (0.015 mg/L) and copper action level (1.3 mg/L) exceedance flags. The 90th percentile is a system-wide statistic, not a reading at any individual home's tap. Data is EPA SDWIS via ECHO. get_water_system shows only the latest period — use this tool for the full history and exceedance pattern. An unknown PWSID returns a no_data result.
| Name | Required | Description | Default |
|---|---|---|---|
| pwsid | Yes | Public Water System ID, e.g. IL0970450 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, closed-world, non-destructive profile, and the description adds real value on top: sort order (latest first), the action-level thresholds used for flags (0.015 mg/L lead, 1.3 mg/L copper), the data provenance (EPA SDWIS via ECHO), and the no_data path for unknown IDs. It stops short of describing output volume, whether periods are paginated, or how many periods typically return, which keeps it from a 5.
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?
Four sentences, front-loaded with the core verb and resource, then the caveat, then the sibling routing. The statistical caveat (90th percentile is system-wide, not a single tap) is not padding — it prevents a likely misinterpretation that would corrupt downstream answers.
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?
Even without an output schema, the description conveys the return shape (90th percentile per monitoring period plus action-level exceedance flags), ordering, thresholds, and the empty-result case. Combined with annotations covering the safety profile, an agent has everything needed to call this and interpret the result.
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 parameter carries an example format, so the baseline is 3. The description earns an extra point by clarifying the semantics of PWSID as identifying exactly one water system and by specifying that an unresolvable PWSID yields a no_data result rather than an error.
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 (lead and copper results for one water system by PWSID) with precise scope: 90th percentile tap samples per Lead and Copper Rule monitoring period. It explicitly distinguishes itself from the sibling get_water_system, so an agent can route correctly 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?
Names the alternative (get_water_system shows only the latest period) and states the exact condition that selects this tool: full history and exceedance pattern. It also documents the unknown-PWSID outcome (no_data result), which is a when-to-expect behavior most definitions omit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PFAS results for one water system by PWSID from EPA's UCMR5 occurrence monitoring (2023-2025): whether the system was sampled, which of the 29 PFAS (plus lithium) were detected, detection counts, and maximum and mean detected concentrations in µg/L and ppt, with the 2024 PFAS MCLs shown as reference context. UCMR5 sampled only a subset of systems; no results means the system was not sampled under UCMR5, not that its water is PFAS-free. UCMR5 is occurrence monitoring, not compliance monitoring, so results are not compliance verdicts. Use this for one known system; use list_systems_with_pfas_detections instead to find or rank systems with detections across a state, county, or single analyte.
| Name | Required | Description | Default |
|---|---|---|---|
| pwsid | Yes | Public Water System ID, e.g. IL0970450 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare read-only/non-destructive/closed-world, but the description adds critical interpretation semantics: empty results mean the system was not sampled under UCMR5 rather than PFAS-free, and UCMR5 is occurrence monitoring, not compliance monitoring. Those two caveats prevent the most likely agent misreporting, which is exactly what annotations cannot convey.
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 scope are front-loaded, then caveats, then the sibling hand-off — a sensible order. It is a dense multi-clause paragraph; the concentration units and MCL-context details are useful but make the first sentence long enough to be harder to scan than it needs to be.
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?
There is no output schema, and the description compensates by describing the shape of the return (detection set, counts, max/mean in µg/L and ppt, MCL reference values). For a single-parameter read tool, nothing an agent needs to call or interpret it 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 coverage is 100% and the single parameter's description already supplies an example format ('IL0970450'). The description reinforces that the key identifies 'one water system' but adds no format, validation, or lookup-fallback detail beyond the schema, so the baseline 3 applies.
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 ('PFAS results for one water system by PWSID') and pins the data source and time window (EPA UCMR5, 2023-2025). It also enumerates what is returned (sampled status, which of 29 PFAS plus lithium detected, counts, max/mean concentrations), which no sibling tool covers.
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?
Explicitly routes the agent: 'Use this for one known system; use list_systems_with_pfas_detections instead to find or rank systems with detections across a state, county, or single analyte.' It names the alternative and the exact conditions selecting each, including the case where the caller has no PWSID and needs discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up one US public water system by its PWSID (e.g. IL0970450). Returns the system's identity, type (community, transient, non-transient non-community), population served, service connections, owner and source type, the counties it serves, its current health-based violations (unresolved MCL, MRDL, and treatment-technique violations) from EPA SDWIS, plus its latest lead/copper 90th-percentile result and a summary of its UCMR5 PFAS sampling (whether sampled, analytes detected, maximum concentration). Use this when you already know the PWSID; if you only have a name or place, use search_water_systems first. This is the bundled overview — for the full monitoring-period lead/copper history use get_system_lead_copper, and for full per-analyte PFAS results use get_system_pfas. An unknown PWSID returns a no_data result, not an empty profile.
| Name | Required | Description | Default |
|---|---|---|---|
| pwsid | Yes | Public Water System ID, e.g. IL0970450 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: an unknown PWSID yields a no_data result rather than an empty profile, which prevents an agent from misreading a miss as a real system with zero violations. It also details what the return contains, though it says nothing about auth, rate limits, or response size/shape beyond field names.
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 identifier are front-loaded in the first clause, with routing guidance and the edge case following. The middle sentence is a long enumeration of returned fields, which is dense but each listed field is decision-relevant for choosing this tool over its siblings; nothing is redundant 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?
There is no output schema, so the description must carry the return contract, and it does so field-group by field-group. Combined with the explicit no_data edge case and the delegation pointers to more detailed siblings, an agent has everything needed to call it correctly and interpret the result.
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?
Only one parameter with 100% schema description coverage, so the baseline is 3. The description repeats the 'PWSID (e.g. IL0970450)' example already present in the schema and adds only the scoping qualifier 'one' system per call; no additional syntax or validation guidance 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 and resource ('Look up one US public water system by its PWSID') and then enumerates the exact payload: identity, type, population, connections, owner/source, counties, health-based violations, lead/copper 90th percentile, and UCMR5 PFAS summary. This clearly separates it from siblings like get_system_lead_copper and get_system_pfas, which are explicitly framed as the deeper-dive versions.
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 an explicit trigger ('Use this when you already know the PWSID'), an explicit fallback ('if you only have a name or place, use search_water_systems first'), and routes to two alternative tools by name for full history versus full per-analyte results. When-to-use, when-to-use-something-else, and which-something-else are all covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every contaminant that has at least one current health-based violation in EPA SDWIS, with the number of open violations and the number of water systems affected, most violations first. Useful for seeing which contaminants drive current US drinking water violations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare that this is a read-only, non-destructive, non-open-world operation. The description adds useful behavioral detail beyond annotations: it specifies the inclusion criterion, returned counts, and most-violations-first ordering. It does not mention pagination or result limits, but the additional context is still substantial.
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 two tight sentences, front-loaded with the core operation and scope. The second sentence adds usage value without repetition or waste.
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 parameters, no output schema, and annotations already covering safety, the description supplies what the agent needs: scope, returned metrics, and ordering. Nothing essential 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?
The tool has zero input parameters, so the baseline is 4. The description appropriately focuses on output semantics rather than inventing parameter behavior.
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 uses a specific verb and resource: it lists contaminants with at least one current health-based violation in EPA SDWIS. It also states the returned metrics and sort order, making it clearly distinguishable from siblings like get_current_health_violations.
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 a clear usage context: seeing which contaminants drive current US drinking water violations. It does not explicitly name when to use a sibling instead, such as get_current_health_violations, so it falls short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List water systems with at least one PFAS detection under EPA UCMR5 occurrence monitoring (2023-2025), worst first by maximum detected concentration. Filter by state, by county (requires state), or by a single analyte (e.g. PFOA, PFOS) to rank by that analyte's maximum. Only systems sampled under UCMR5 can appear; absence means not sampled, not PFAS-free.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 50, max 500) | |
| state | No | Two-letter state code, e.g. IL | |
| county | No | County name as reported to SDWIS, e.g. COOK (requires state) | |
| analyte | No | UCMR5 analyte name, e.g. PFOA, PFOS, PFHxS, PFBS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/non-destructive, so the bar is lower; the description still adds real context beyond them — the UCMR5 sampling-coverage caveat and the default sort by max concentration. It does not discuss result pagination or how ties are broken, but nothing contradicts the annotations.
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?
Three dense sentences, zero filler, with the identify-and-sort behavior front-loaded before the filter options and the coverage caveat last. 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?
There is no output schema, yet the description still conveys what comes back (systems, ordered worst-first), what filters do, and the critical limitation that unsampled systems are omitted. An agent can call this correctly and interpret empty results without further information.
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 baseline is 3, but the description adds semantics the schema lacks: county requires state, and passing an analyte changes the ranking key ('rank by that analyte's maximum'). That is genuine value beyond the parameter descriptions.
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?
Specific verb+resource ('List water systems') with precise scope ('at least one PFAS detection under EPA UCMR5 occurrence monitoring 2023-2025') and even the default ordering ('worst first by maximum detected concentration'). It is clearly distinguishable from the system-level sibling get_system_pfas and from list_contaminants_with_violations.
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?
Explains the three filtering modes (state, county-requires-state, single analyte) and when the analyte filter changes ranking. It also gives an interpretation rule: 'absence means not sampled, not PFAS-free.' It does not explicitly name when to prefer a sibling (e.g. get_system_pfas for one system), so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search US public water systems by name, and optionally narrow by state (two-letter code), county name as reported to SDWIS (requires state), system type code (CWS, NTNCWS, TNCWS), or active systems only. Results are ordered by population served, largest first, and each result includes its count of current health-based violations. Returns brief records at most limit at a time (default 50, max 500) with no offset paging — narrow the filters to dig deeper. Use get_water_system with a result's PWSID for that system's full profile, violations, lead/copper and PFAS detail.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | System type code: CWS, NTNCWS, or TNCWS | |
| limit | No | Max results (default 50, max 500) | |
| query | No | Name fragment to match, e.g. 'Springfield' | |
| state | No | Two-letter state code, e.g. IL | |
| county | No | County name as reported to SDWIS, e.g. COOK (requires state) | |
| active_only | No | Only active systems |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the readOnly/destructive annotations: result ordering (population served, largest first), the shape of each record (brief, includes current health-based violation count), and the absence of offset paging with a 500 cap. It does not discuss rate limits or what fields a 'brief record' contains beyond violations, which keeps it short of a 5.
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?
Three dense sentences, front-loaded with the core action and narrowing options, then return behavior, then the routing instruction. No filler and nothing repeated from the schema for its own sake.
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 describing ordering, record brevity, and the violation count in results. With six optional params, the filtering model and the escape hatch to the detail tool, 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%, so the baseline is 3, but the description adds operative meaning: county requires state, the type codes are the only valid values, and the limit interacts with the no-offset-paging design so the agent knows to filter rather than page. It largely restates the schema's own parameter docs, which caps it at 4.
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?
Specific verb+resource ('Search US public water systems') with the searchable facets and the scope ('US public') stated up front. It is clearly distinguished from the sibling get_water_system, which the description explicitly positions as the detail-retrieval counterpart.
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?
Explicitly states when this tool applies (name search with optional narrowing) and when to switch: 'Use get_water_system with a result's PWSID for that system's full profile, violations, lead/copper and PFAS detail.' It also prescribes the correct strategy when results are insufficient ('narrow the filters to dig deeper') rather than paging.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_system_lead_copperget_system_pfaslist_systems_with_pfas_detectionsget_county_water_summaryget_current_health_violationsget_state_water_summaryget_water_systemlist_contaminants_with_violationssearch_water_systemsEPA facility compliance: 3.2M regulated facilities, unified compliance profiles. No key.
Query US tap-water quality from the EPA's SDWIS records — by city, system, or contaminant.
Federal environmental records near any US location, with dates and provenance; never a safety score.
Water Quality Portal (WQP) MCP — US ambient water-chemistry monitoring
Add one secure layer between your agents and this server.