Skip to main content
Glama

Search Drinking Water Systems

epa_water_search_systems
Read-onlyIdempotent

Drinking water (SDWIS): Search public water systems by state, ZIP code, or county served. Returns system name, PWSID, population served, primary water source, and activity status, in PWSID order; page through a large match with offset and nextOffset. zip_code matches a system's address of record, often an owner's or operator's office far from the area it serves; county (with state) finds the systems serving an area. With has_violation, returns only systems with a current SDWA violation in EPA's ECHO, which applies EPA's Enforcement Response Policy, so it flags fewer systems than SDWIS's unresolved violation records. At least one of state or zip_code is required. Pass a returned pwsid as registry_id to epa_echo_get_facility for the system's drinking-water violations: contaminant, measured level, MCL, status, and enforcement actions.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "epa_water_search_systems"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of systems to return in one call. Default 25; a larger value returns at most 1,000 and says so. Page past it with offset and nextOffset.
stateNo2-letter US state or territory code (e.g. "WA", "CA"), or an EPA region code 01–10 for tribal systems, whose primacy agency is the EPA region
countyNoCounty the system serves, e.g. "King"; requires state. Case-insensitive, and a trailing "County", "Parish", "Borough", "City and Borough", "Census Area", or "Municipality" is dropped, so "Anchorage" matches Anchorage Municipality. A system matches when one of the counties it serves is this county, so "Harris" does not match Harrison. Punctuation is matched as written ("St. Tammany").
offsetNoNumber of systems to skip before this page (default 0). Pass the previous call's nextOffset to continue; a value past the end returns an empty page.
pws_typeNoFilter by public water system type: community=permanent residences, non-transient=regular non-residents (schools, businesses), transient=occasional users (campgrounds)
zip_codeNo5-digit ZIP code of the water system's address of record — often its owner's or operator's office, which can be far from the area the system serves. Matches stored ZIP+4s within it; a ZIP+4 searches its 5-digit ZIP. Use county for the systems serving an area.
active_onlyNoWhen true, return only systems SDWIS lists as active (activity code A). The default false also returns inactive systems and ones changed to non-public.
has_violationNoWhen true, return only systems with a current SDWA violation in EPA's ECHO, its compliance status for the system, which clears violations SDWIS still lists as unresolved. Works with state, zip_code, county, or a combination.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
noticeNoPresent when a check stopped early (a ZIP or county has_violation check hit 1,000 systems, or the county check its read limit); nextOffset continues.
messageNoRecovery hint on an empty result; absent otherwise.
systemsNoMatching systems, PWSID order
guidanceNoPresent when more systems may follow: the continuing offset.
nextOffsetNoNext offset; absent on the last page.
totalCountNoMatches before limit and offset; present only when the call saw the whole match (offset 0 and no nextOffset, or a state has_violation search over ECHO's full violator list).
limitNoticeNoPresent when a smaller limit than requested applied; says why.
effectiveQueryNoThe search as sent upstream, in input names: values, match modes, and result-changing defaults, "; "-joined.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changed
    • changedInput schema / properties / limit / default
      Previous value: -50New value: +25
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of systems to return in one call (1–200, default 50). A larger value, up to 5,000, returns 200 with a notice. Page past it with offset and nextOffset."New value: +"Number of systems to return in one call. Default 25; a larger value returns at most 1,000 and says so. Page past it with offset and nextOffset."
    • changedInput schema / properties / limit / maximum
      Previous value: -5000New value: +9007199254740991
    • changedOutput schema / properties / effectiveQuery / description
      Previous value: -"The search as the server sent it upstream, in this tool's input names: normalized values, how each text filter matched (\"=\" exact, \"contains\", \"begins with\", \"has words\"), and defaults that change what comes back. Terms are separated by \"; \"."New value: +"The search as sent upstream, in input names: values, match modes, and result-changing defaults, \"; \"-joined."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_geographic_filter`: Neither state nor zip_code was provided. `county_requires_state`: county was provided without state. `invalid_state`: state has the 2-character form but is not a US state, DC, territory, freely associated state, UM, NN, or EPA region code. `unmatchable_filter`: county has no letter or digit for EPA's DMAP service to match on. `filter_too_long`: county makes a request longer than EPA's DMAP service accepts. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_geographic_filter`: Neither state nor zip_code was given. `county_requires_state`: county without state. `invalid_state`: state is not a US state, territory, or EPA region code. `unmatchable_filter`: county has no letter or digit. `filter_too_long`: county makes the request too long. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / guidance / description
      Previous value: -"Present when more systems may follow: the offset that continues the search."New value: +"Present when more systems may follow: the continuing offset."
    • changedOutput schema / properties / limitNotice / description
      Previous value: -"Present when limit was above the cap and the call returned the cap instead."New value: +"Present when a smaller limit than requested applied; says why."
    • changedOutput schema / properties / message / description
      Previous value: -"Recovery hint when no systems are found. Absent when systems are returned."New value: +"Recovery hint on an empty result; absent otherwise."
    • changedOutput schema / properties / nextOffset / description
      Previous value: -"Offset of the next page: present exactly when more records follow, absent on the last page. Pass it as offset to continue."New value: +"Next offset; absent on the last page."
    • changedOutput schema / properties / notice / description
      Previous value: -"Present when a check ended before the page filled: a ZIP or county has_violation check read its 1,000-system limit, or the county check reached its read limit with few whole-name matches. nextOffset continues from where it stopped."New value: +"Present when a check stopped early (a ZIP or county has_violation check hit 1,000 systems, or the county check its read limit); nextOffset continues."
    • changedOutput schema / properties / systems / description
      Previous value: -"Matching public water systems, in PWSID order"New value: +"Matching systems, PWSID order"
    • changedOutput schema / properties / systems / items / description
      Previous value: -"Public water system record with PWSID, population served, and violation status"New value: +"One water system"
    • changedOutput schema / properties / systems / items / properties / city / description
      Previous value: -"City of the water system's address of record — often its owner's or operator's office, not necessarily the area it serves"New value: +"Of the address of record, often an owner's or operator's office, not the area served"
    • changedOutput schema / properties / systems / items / properties / hasViolation / description
      Previous value: -"True when ECHO reports a current SDWA violation for this system. Present only on has_violation searches, which return only such systems."New value: +"True when ECHO reports a current SDWA violation; only on has_violation searches"
    • changedOutput schema / properties / systems / items / properties / isActive / description
      Previous value: -"Whether this water system is currently active"New value: +"Whether currently active"
    • changedOutput schema / properties / systems / items / properties / name / description
      Previous value: -"Water system name"New value: +"System name"
    • changedOutput schema / properties / systems / items / properties / populationServed / description
      Previous value: -"Estimated population served by this water system"New value: +"Estimated"
    • changedOutput schema / properties / systems / items / properties / primarySourceCode / description
      Previous value: -"Primary water source code (e.g. GW=groundwater, SW=surface water)"New value: +"Such as GW groundwater or SW surface water"
    • changedOutput schema / properties / systems / items / properties / pwsid / description
      Previous value: -"Public Water System ID (PWSID) — unique system identifier"New value: +"Public water system ID"
    • changedOutput schema / properties / systems / items / properties / state / description
      Previous value: -"Primacy agency code: a 2-letter state abbreviation, or the EPA region code 01–10 of a tribal system"New value: +"Primacy agency: state code, or EPA region 01–10 for a tribal system"
    • changedOutput schema / properties / systems / items / properties / type / description
      Previous value: -"PWS type code: CWS=Community, NTNCWS=Non-transient non-community, TNCWS=Transient non-community"New value: +"CWS community, NTNCWS non-transient non-community, TNCWS transient non-community"
    • changedOutput schema / properties / systems / items / properties / zip / description
      Previous value: -"ZIP code of the water system's address of record (the value zip_code matches)"New value: +"Of the address of record, which zip_code matches"
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Systems matched before limit and offset. Present when the call saw the whole match: a search from offset 0 with no nextOffset, or a state has_violation search that checked ECHO's whole violator list. Absent otherwise, since EPA's DMAP service reports no match count (follow nextOffset instead)."New value: +"Matches before limit and offset; present only when the call saw the whole match (offset 0 and no nextOffset, or a state has_violation search over ECHO's full violator list)."
  2. Changed22 schema fields changed
    • addedInput schema / properties / active_only
      Added value: +{
      +  "default": false,
      +  "description": "When true, return only systems SDWIS lists as active (activity code A). The default false also returns inactive systems and ones changed to non-public.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / county
      Added value: +{
      +  "description": "County the system serves, e.g. \"King\"; requires state. Case-insensitive, and a trailing \"County\", \"Parish\", \"Borough\", \"City and Borough\", \"Census Area\", or \"Municipality\" is dropped, so \"Anchorage\" matches Anchorage Municipality. A system matches when one of the counties it serves is this county, so \"Harris\" does not match Harrison. Punctuation is matched as written (\"St. Tammany\").",
      +  "maxLength": 4094,
      +  "type": "string"
      +}
    • changedInput schema / properties / has_violation / description
      Previous value: -"When true, return only systems with an open SDWIS violation (not yet returned to compliance). Works with state, zip_code, or both."New value: +"When true, return only systems with a current SDWA violation in EPA's ECHO, its compliance status for the system, which clears violations SDWIS still lists as unresolved. Works with state, zip_code, county, or a combination."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of systems to return (1–200)"New value: +"Maximum number of systems to return in one call (1–200, default 50). A larger value, up to 5,000, returns 200 with a notice. Page past it with offset and nextOffset."
    • changedInput schema / properties / limit / maximum
      Previous value: -200New value: +5000
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "Number of systems to skip before this page (default 0). Pass the previous call's nextOffset to continue; a value past the end returns an empty page.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / state / description
      Previous value: -"2-letter US state abbreviation (e.g. \"WA\", \"CA\")"New value: +"2-letter US state or territory code (e.g. \"WA\", \"CA\"), or an EPA region code 01–10 for tribal systems, whose primacy agency is the EPA region"
    • addedInput schema / properties / state / pattern
      Added value: +"^\\s*(?:[A-Za-z0-9]{2}\\s*)?$"
    • changedInput schema / properties / zip_code / description
      Previous value: -"5-digit ZIP code of the water system's address of record — often its owner's or operator's office, which can be far from the area the system serves"New value: +"5-digit ZIP code of the water system's address of record — often its owner's or operator's office, which can be far from the area the system serves. Matches stored ZIP+4s within it; a ZIP+4 searches its 5-digit ZIP. Use county for the systems serving an area."
    • addedInput schema / properties / zip_code / pattern
      Added value: +"^\\s*(?:\\d{5}(?:-?\\d{4})?\\s*)?$"
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "systems",
      -      "totalCount"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "systems"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / effectiveQuery
      Added value: +{
      +  "description": "The search as the server sent it upstream, in this tool's input names: normalized values, how each text filter matched (\"=\" exact, \"contains\", \"begins with\", \"has words\"), and defaults that change what comes back. Terms are separated by \"; \".",
      +  "type": "string"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_geographic_filter`: Neither state nor zip_code was provided. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_geographic_filter`: Neither state nor zip_code was provided. `county_requires_state`: county was provided without state. `invalid_state`: state has the 2-character form but is not a US state, DC, territory, freely associated state, UM, NN, or EPA region code. `unmatchable_filter`: county has no letter or digit for EPA's DMAP service to match on. `filter_too_long`: county makes a request longer than EPA's DMAP service accepts. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_geographic_filter"
      -]New value: +[
      +  "no_geographic_filter",
      +  "county_requires_state",
      +  "invalid_state",
      +  "unmatchable_filter",
      +  "filter_too_long"
      +]
    • addedOutput schema / properties / guidance
      Added value: +{
      +  "description": "Present when more systems may follow: the offset that continues the search.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / limitNotice
      Added value: +{
      +  "description": "Present when limit was above the cap and the call returned the cap instead.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / nextOffset
      Added value: +{
      +  "description": "Offset of the next page: present exactly when more records follow, absent on the last page. Pass it as offset to continue.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Present when the has_violation check read only part of what it needed — the first 1,000 open violation records for the state, the first 1,000 systems in the ZIP, or the first 1,000 open violation records for a group of the ZIP’s systems — so violating systems outside that part may be missing from the results."New value: +"Present when a check ended before the page filled: a ZIP or county has_violation check read its 1,000-system limit, or the county check reached its read limit with few whole-name matches. nextOffset continues from where it stopped."
    • changedOutput schema / properties / systems / description
      Previous value: -"Matching public water systems"New value: +"Matching public water systems, in PWSID order"
    • changedOutput schema / properties / systems / items / properties / hasViolation / description
      Previous value: -"True when SDWIS lists an open violation for this system. Present only on has_violation searches, which return only such systems."New value: +"True when ECHO reports a current SDWA violation for this system. Present only on has_violation searches, which return only such systems."
    • changedOutput schema / properties / systems / items / properties / state / description
      Previous value: -"2-letter state abbreviation (primacy agency code)"New value: +"Primacy agency code: a 2-letter state abbreviation, or the EPA region code 01–10 of a tribal system"
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Number of systems returned"New value: +"Systems matched before limit and offset. Present when the call saw the whole match: a search from offset 0 with no nextOffset, or a state has_violation search that checked ECHO's whole violator list. Absent otherwise, since EPA's DMAP service reports no match count (follow nextOffset instead)."
  3. Added

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, and open-world, so the safety profile is covered. The description still adds real behavioral value: PWSID result ordering, offset/nextOffset paging, the effective 1,000-row ceiling over the schema's larger maximum, and the caveat that ECHO's Enforcement Response Policy clears violations SDWIS still lists as unresolved. It does not mention rate limits or error behavior, so full marks are not warranted, but the disclosure is well above the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded, with purpose first, then the ZIP/county caveat, then the violation caveat, then the follow-up call. The ZIP-vs-county caveat is repeated almost verbatim in the zip_code schema property, so a sentence of redundancy survives, but nothing is wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an eight-parameter, open-world search tool with an output schema, this covers the operational essentials: required-key precondition, ordering, pagination strategy, and the semantic difference between the two geographic filters plus the violation flag. An agent can call it correctly and page results without opening anything else.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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, and most description text (ZIP vs. county semantics) duplicates what the schema already says. The one genuinely additive element is the cross-parameter constraint that at least one of state or zip_code is required, which the schema's empty required list does not express.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Search public water systems") scoped to the SDWIS drinking-water program, and immediately names the three lookup keys (state, ZIP, county). It also distinguishes itself from the ECHO family by pointing to epa_echo_get_facility as the drill-down for violation detail, so an agent can place it precisely among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Goes beyond mere context to explicit routing rules: use zip_code for a system's address of record versus county (with state) for systems serving an area, and use has_violation only when ECHO's ERP-filtered violation view is wanted. It states the invocation precondition ("At least one of state or zip_code is required") and names the correct next call, leaving little to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.