epa-mcp-server

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

Annotations already cover readOnly/idempotent/openWorld, but the description adds substantial behavior beyond them: the 50-mile nearest-monitor radius, per-pollutant monitor sourcing within one reporting area, typical forecast day counts (one to five), agencies that report a category without an AQI number, empty results with issued dates in the message, and a ~1 hour cache. The preliminary-data caveat is unusual and valuable.

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 purpose and location requirements, then modes, then caveats; every sentence carries information. It is a dense single paragraph of roughly 150 words, which is on the long side and would scan better split into purpose / location / modes / caveats.

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?

Despite an output schema existing, the description explains what each mode returns and its known quirks (missing AQI numbers, multiple monitors per area, empty-result messaging). Combined with the data-quality warning, an agent has everything needed to call and interpret 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%, so the baseline is 3. The description goes past the schema by explaining that forecast_date is rejected in current mode and by clarifying that omitting it returns every issued day, adding consequence-level meaning rather than restating field 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?

States a specific verb (get), resource (current AQI observations or issued AQI forecast), and source (AirNow API) with the geographic scope (US location). Sibling tools all belong to other EPA programs (ECHO, EJScreen, TRI, Superfund, water), so the AirNow framing alone distinguishes it.

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 location rules (zip_code OR both latitude and longitude), explicit mode selection guidance, and an explicit exclusion: 'suitable for awareness, not regulatory, trend, or enforcement decisions.' It also states that current mode rejects forecast_date, removing a likely misuse path.

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=true, idempotent=true, openWorld=true, so the safety profile is covered; the description adds substantive scope that annotations cannot: the newest 100 inspections, a five-year monitoring and enforcement window, and that penalties are included. It does not mention rate limits or auth requirements, 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?

Purpose and the return-payload enumeration are front-loaded, then the routing sentences follow. The long middle sentence is dense but every clause names a distinct returned section; slightly over-enumerated given an output schema exists, but no 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?

Output schema exists, so return values needn't be restated, yet the description's summary of the payload is still helpful for tool selection. Single-parameter tool with full schema coverage and a clear entry point; nothing an agent needs to invoke it 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?

The single registry_id parameter has 100% schema description coverage that already names it as an FRS Registry ID obtained from epa_echo_search_facilities. The description repeats the same sourcing hint and adds no format, validation, or 404-behavior detail, so the schema is doing the work.

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 ('Retrieve a full compliance profile for a single EPA-regulated facility') keyed to a named identifier, and enumerates the content of the payload. It is clearly differentiated from epa_echo_search_facilities and epa_echo_search_violations, which are named explicitly.

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 routing: use epa_echo_search_facilities to discover Registry IDs, and use epa_echo_search_violations for area-level enforcement discovery instead. It also points to epa_tri_get_facility_releases for the TRI IDs it returns, so the when/when-not conditions are covered.

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/openWorld/idempotent, so the safety profile is covered; the description adds real value beyond that by disclosing the timeout behavior for unscoped searches and the concrete return payload (registry ID, coordinates, county FIPS, per-program flags, five-year inspection and penalty totals, TRI release totals). Pagination and the default limit are left to the schema, which is why this is not 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, each carrying distinct information, with the purpose and the payload front-loaded before the operating constraint. No restatement of the tool name or 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 10-parameter read-only search with 100% schema coverage, full annotations, and an output schema, the description covers everything remaining: scope, the return fields, the hard filter requirement, the single-program limitation, and the handoff to epa_echo_get_facility. Nothing an agent needs to call this correctly 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%, so the baseline is 3, but the description adds semantics the schema can't: that a program filter accepts only one value per search, and that latitude/longitude/radius_miles must be supplied as a complete triple. It also frames the geographic filters as a required disjunction, which is a cross-parameter constraint the schema doesn't express.

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?

Names a specific verb (search) plus resource (EPA-regulated facilities) and enumerates the filter axes (location, program, compliance status) and covered programs (CAA, CWA, RCRA, TRI, SDWA). It also distinguishes itself from the sibling epa_echo_get_facility by explaining that the returned Registry IDs feed that tool, so an agent can route between them 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?

Explicitly states the hard precondition that at least one geographic filter (zip_code, state, city, or a complete lat+lon+radius triple) is required and that unscoped searches time out, which is exactly the kind of routing rule an agent needs. It also explains the proximity-search path. What's missing is guidance on when to use this versus epa_echo_search_violations, given that has_violation overlaps with that sibling's purpose.

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/openWorld, so the safety profile is covered; the description adds the non-obvious constraint that state or zip_code is mandatory — information the schema does not encode (required: 0). It does not disclose the civil-only limitation of date filters, but that caveat is carried in the schema's parameter descriptions.

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 compact sentences: purpose and filters first, return contents second, routing and constraint last. No filler and the most decision-relevant information is front-loaded.

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 an output schema present and 100% parameter coverage, the description covers purpose, routing, and the mandatory-filter rule. Minor gaps: no statement about result ordering or pagination behavior when limit caps the result set.

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% and the parameters are documented in detail in the schema (enum meanings, date format, the program-matching nuance). The description only restates the filter axes and the one-of requirement, adding little meaning beyond the schema; 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?

Specific verb+resource ("Search EPA civil and criminal enforcement cases") with explicit filter dimensions and a clear distinction from epa_echo_get_facility, which handles single-facility lookups. An agent can tell what this returns (case identifier, programs, penalty, dates, case type) 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?

Gives the use case positively ("area-level violation discovery") and names the alternative tool with the condition that selects it (single known facility → epa_echo_get_facility). It also states the minimal invocation requirement: at least one of state or zip_code.

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?

Adds substantial context beyond the readOnly/idempotent/openWorld hints: the exact data vintage (EJScreen v2.2, 2022), the serving path (community-maintained EJAM API, not a live EPA endpoint after 2025 discontinuation), and the out-of-coverage response behavior. This is exactly the provenance an agent needs to judge trustworthiness and failure modes.

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?

Placeholder — see justification text in the conciseness_structure field of the final assessment.

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 an output schema, 100% parameter coverage and annotations already present, the remaining burden is provenance and edge-case behavior — both covered (EJAM rehosting caveat, US-coverage fallback, buffer cap). Nothing needed to call it 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 coverage is 100%, with unit conversion, buffer bounds and degree ranges all documented in the schema itself. The description restates the default and the 15-mile ceiling but adds no format or interpretation detail beyond that, 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?

Names a specific verb and resource (EJScreen environmental-justice indicators) scoped to 'a point and surrounding buffer', which cleanly separates it from the sibling tools that cover air quality, facilities, violations, TRI releases and water systems. The indicator families named confirm what the agent gets back.

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 usage context — supply latitude, longitude and a buffer distance (default 1 mile, max 15 miles) — and states the US-only boundary condition with a stated fallback ('coverage note'). It does not name an alternative tool for non-point or non-US queries, so it stops short of explicit when-not 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 declare readOnly/idempotent/openWorld, so the bar is lower, yet the description still adds real behavior: the returned field set, nearest-first ordering for proximity queries, and a 50-second shared deadline with mitigation advice. That timeout budget is operationally valuable and appears nowhere in 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?

Front-loaded with what the tool is and what it returns, then the two input modes, then the timeout caveat. Every sentence carries information; there is no filler or restatement of the title.

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 an 8-parameter read-only search with a full schema and an output schema, the description covers purpose, inputs, ordering, and failure behavior. Listing return fields is slightly redundant given the output schema exists, but nothing an agent needs to call it 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 coverage is 100%, so baseline is 3, but the description adds the either/or mode contract (state/city/ZIP versus latitude+longitude+radius) that governs which parameters must be combined, which the schema only hints at per-field. That combination semantics is genuinely additive.

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 (Search) plus resource (Superfund/CERCLA/SEMS sites) plus the two search axes (location, NPL status). The scope is clearly distinct from the EPA siblings, which cover air, ECHO facilities, TRI releases, and water systems.

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 the triggering question form ("are there Superfund sites near X") and gives remedial guidance when a proximity search times out (narrow radius, add filters). It does not name when to prefer a sibling tool instead, but the domain is non-overlapping enough that this is a minor gap.

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/openWorld, so the description's value-add is the domain caveats: ~18-month reporting lag, pound units with dioxin converted from grams and flagged via reportedUnit. It stops short of describing truncation/pagination behavior, though the 500-filing cap is documented in the schema rather than here.

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 purpose, then return shape, units, latency caveat, and identifier sourcing — a sensible order with no filler sentences. Minor redundancy: the '12-digit EPA Registry ID matches no TRI records' warning repeats verbatim what the facility_id schema description already states.

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?

Output schema exists so return values needn't be enumerated, yet the description still summarizes the record shape and unit handling. Combined with the lag caveat and identifier sourcing, an agent has everything needed to call it correctly on the first try.

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; the description earns above that by giving the provenance and exact format of facility_id ('15-character TRI facility ID') and the negative case of the 12-digit Registry ID, which is the most likely invocation error. It adds little on year/chemical_name beyond what the schema says.

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 ('Query Toxic Release Inventory annual chemical release data for a specific facility') and immediately distinguishes itself from the sibling search tool by scoping to one facility. An agent can tell it apart from epa_tri_search_releases 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?

Explicitly routes the agent: get facility_id from epa_tri_search_releases (or from triFacilityIds of epa_echo_get_facility if the agent holds a Registry ID), and warns that a 12-digit Registry ID matches nothing. This is when-to-use plus how-to-source-the-key, with an explicit exclusion.

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 read-only/idempotent safety, and the description adds material behavior beyond them: an ~18-month data lag, the ~20-second latency cost of include_release_breakdown when uncached, unit handling (pounds, grams conversion for dioxins marked via reportedUnit), and newest-first ordering. This is exactly the extra context annotations cannot supply.

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 what the tool returns before branching into the include_release_breakdown tradeoff and alternative-tool routing, so an agent can stop reading once it has what it needs. It is dense and slightly long, but nearly every clause carries information 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?

Given six parameters, an output schema, and read-only annotations, the description supplies everything an agent needs: return fields, unit conventions, latency tradeoff, data staleness, and sibling routing. Nothing required to call it 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: quantities are in pounds, dioxin-like compounds are converted from grams and flagged with reportedUnit, and time-related defaults (newest-first so limit keeps recent filings). It stops short of documenting every parameter but meaningfully enriches the key ones.

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 (Search) and resource (Toxic Release Inventory data) with clear scope: facilities in a state or county, for one year or all years newest-first. It explicitly distinguishes itself from the sibling epa_tri_get_facility_releases, so the boundary is unambiguous.

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

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

Names concrete use cases (identify top polluters in an area, build an environmental exposure profile) and the alternative tool with its selecting condition ('for detailed release records for a single facility'). When-to-use and when-to-use-something-else are both explicit.

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 read-only, idempotent, open-world behavior, so the bar is lower; the description still adds real domain context by defining what an 'open violation' means — not returned to compliance, or not closed out when the system was deactivated. It omits any statement about result-set size limits or pagination, which matters for a search tool.

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 sentences, front-loaded with the verb and resource, then output fields, then the has_violation nuance, then the constraint. Slight redundancy in repeating 'drinking water (SDWIS)' twice in the opening clause, but no wasted content overall.

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 an output schema and full parameter documentation already present, the description only needed to add domain semantics and invocation rules, and it does both. The one gap is behavior for large result sets relative to the 1–200 limit, which an agent would want to know before calling.

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; the description goes beyond it by restating the state/zip_code at-least-one rule and by unpacking the has_violation semantics more fully than the schema's one-line note. It adds nothing about limit or pws_type, leaving those entirely to 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 — 'Search drinking water systems (SDWIS) by state or ZIP code' — and enumerates the returned fields, so the agent knows exactly what it gets. It doesn't name or contrast any sibling, though the drinking-water domain is unmistakably distinct from the air/facility/superfund siblings, so confusion risk is low.

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?

'At least one of state or zip_code is required' gives a concrete invocation precondition, and the has_violation sentence explains the condition under which the tool narrows to non-compliant systems. It stops short of stating when not to use it or what to do when neither filter is available.

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