gov-data-mcp 1.2.4 → 1.2.6

package/README.md

@@ -1,6 +1,6 @@
 # gov-data-mcp
 
-**122 US government open-data tools, as one MCP server.**
+**123 US government open-data tools, as one MCP server.**
 
 EPA, FEMA, USGS, NOAA, FAA, USACE, FDIC, HUD, NRCS, HRSA, CMS, county assessor rolls and state licensing boards — all reachable as agent-callable tools, all reading directly from official government APIs and bulk files. No scraping, no HTML parsing, no rate-limit roulette.
 
@@ -49,13 +49,13 @@ Claude Desktop reads `claude_desktop_config.json`; Claude Code reads `.mcp.json`
 | `parcel-owner-lookup` | Assessor-roll owner of record for an address |
 | `license-verifier` | 19 professional licensing boards across 9 states + OIG exclusions |
 
-**Plus three tools that reach the other 110:**
+**Plus three tools that reach the other 111:**
 
 - `search-gov-data-tools` — find a tool by keyword, agency or topic
 - `describe-gov-data-tool` — full input schema for any tool in the catalog
 - `run-gov-data-tool` — run any tool in the catalog
 
-The catalog is bundled, so discovery costs nothing. Ask your agent *"what government data tools do you have for flood risk?"* and it will search all 122.
+The catalog is bundled, so discovery costs nothing. Ask your agent *"what government data tools do you have for flood risk?"* and it will search all 123.
 
 <!-- PRESETS:START -->
 ## Vertical presets
@@ -169,7 +169,27 @@ npx awal x402 pay 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=5&
 # → returns a bearer token; export it as APIFY_TOKEN and start this server as usual
 ```
 
-The prepaid balance is an absolute spending cap and expires after 14 days. Every tool here charges only per result — none pass platform usage through, none require full permissions, and none run in Standby mode, which are the three things that make an Actor ineligible. Prices are in the catalog (`usdPer1000Results` on every search hit), so an agent can see the cost before spending.
+The prepaid balance is an absolute spending cap and expires after 14 days. Every tool here charges per result or per generated report. None pass platform usage through, none require full permissions, and none run in Standby mode, which are the three things that make an Actor ineligible. Prices are in the catalog (`usdPerUnit` and `priceUnit` on every search hit, plus `usdPer1000Results` for per-row tools), so an agent can see the cost before spending.
+
+## Calling the tools well (guide for agents)
+
+The most common way to waste a call is to guess the input: no state, no coordinates, a misspelled field. These tools then refuse the question, or match nothing, and the caller still pays a fractional actor-start fee. The server helps an agent avoid that in four ways:
+
+1. **An agent guide in the handshake.** The MCP `initialize` response carries `instructions`. They cover the search → describe → run workflow, scoping every call, real codes and ISO dates, starting small, and how to read failures, zero rows and `null`.
+2. **Verified example inputs.** `describe-gov-data-tool` (free) returns:
+   - `must_supply`: the fields you have to provide.
+   - `example_input`: the actor's prefill, which Apify's own QA runs every few days and which returns rows.
+   - Up to two `examples`: inputs from the actor's published, run-verified demo tasks, each with a human title.
+
+   Start from one of them and change only the values you need.
+3. **A free local check before any metered run.** A missing required field, an input name the tool doesn't have, or a value outside a closed vocabulary is reported with `run_status: NOT_RUN_INPUT_INVALID` and the example to copy. Nothing runs and nothing is charged.
+4. **A next step on every unhelpful result.** A failed run returns the actor's own reason in `note`, plus `next_step`, `must_supply` and `example_input`. A zero-row success says to check spelling, state code, radius and date window before concluding that nothing exists.
+
+Example of a well-scoped first call:
+
+```json
+{"tool": "medicaid-exclusion-screener", "input": {"mode": "screen", "targets": [{"npi": "1972902351"}, {"name": "Jane Doe", "dob": "1970-01-01"}]}}
+```
 
 ## On honest answers
 
@@ -187,13 +207,13 @@ The underlying actors carry the same discipline: per-source status on every row,
 <!-- COVERAGE:START -->
 ## Coverage
 
-**122 tools**, every one reading an official US government API or bulk file. The MCP server exposes 15 of them directly — twelve named tools plus `search-gov-data-tools`, `describe-gov-data-tool` and `run-gov-data-tool`, which reach the rest — because agents choose badly when handed more than about twenty tools.
+**123 tools**, every one reading an official US government API or bulk file. The MCP server exposes 15 of them directly — twelve named tools plus `search-gov-data-tools`, `describe-gov-data-tool` and `run-gov-data-tool`, which reach the rest — because agents choose badly when handed more than about twenty tools.
 
 Each entry links to its full input/output schema, pricing and worked examples.
 
-**Contamination & environmental due diligence** (18)
+**Contamination & environmental due diligence** (19)
 
-[epa-airtoxscreen-cancer-risk-screener](https://apify.com/malonestar/epa-airtoxscreen-cancer-risk-screener) · [epa-contaminated-site-screener](https://apify.com/malonestar/epa-contaminated-site-screener) · [epa-drinking-water-quality-screener](https://apify.com/malonestar/epa-drinking-water-quality-screener) · [epa-ghgrp-emitter-screener](https://apify.com/malonestar/epa-ghgrp-emitter-screener) · [epa-impaired-waters-303d-screener](https://apify.com/malonestar/epa-impaired-waters-303d-screener) · [epa-nonattainment-air-permit-screener](https://apify.com/malonestar/epa-nonattainment-air-permit-screener) · [epa-rcra-corrective-action-cleanup-monitor](https://apify.com/malonestar/epa-rcra-corrective-action-cleanup-monitor) · [epa-rcra-hazwaste-generator-rollup](https://apify.com/malonestar/epa-rcra-hazwaste-generator-rollup) · [epa-repowering-brownfield-to-solar-site-finder](https://apify.com/malonestar/epa-repowering-brownfield-to-solar-site-finder) · [epa-sole-source-aquifer-screener](https://apify.com/malonestar/epa-sole-source-aquifer-screener) · [epa-tri-facility-release-rollup](https://apify.com/malonestar/epa-tri-facility-release-rollup) · [epa-tsca-cdr-chemical-site-screener](https://apify.com/malonestar/epa-tsca-cdr-chemical-site-screener) · [erns-nrc-release-incident-screener](https://apify.com/malonestar/erns-nrc-release-incident-screener) · [fuds-defense-site-screener](https://apify.com/malonestar/fuds-defense-site-screener) · [historic-land-use-sic-contaminant-screener](https://apify.com/malonestar/historic-land-use-sic-contaminant-screener) · [site-due-diligence-bundle](https://apify.com/malonestar/site-due-diligence-bundle) · [state-tank-spill-registry-screener](https://apify.com/malonestar/state-tank-spill-registry-screener) · [usgs-historical-topo-records-review](https://apify.com/malonestar/usgs-historical-topo-records-review)
+[environmental-records-report](https://apify.com/malonestar/environmental-records-report) · [epa-airtoxscreen-cancer-risk-screener](https://apify.com/malonestar/epa-airtoxscreen-cancer-risk-screener) · [epa-contaminated-site-screener](https://apify.com/malonestar/epa-contaminated-site-screener) · [epa-drinking-water-quality-screener](https://apify.com/malonestar/epa-drinking-water-quality-screener) · [epa-ghgrp-emitter-screener](https://apify.com/malonestar/epa-ghgrp-emitter-screener) · [epa-impaired-waters-303d-screener](https://apify.com/malonestar/epa-impaired-waters-303d-screener) · [epa-nonattainment-air-permit-screener](https://apify.com/malonestar/epa-nonattainment-air-permit-screener) · [epa-rcra-corrective-action-cleanup-monitor](https://apify.com/malonestar/epa-rcra-corrective-action-cleanup-monitor) · [epa-rcra-hazwaste-generator-rollup](https://apify.com/malonestar/epa-rcra-hazwaste-generator-rollup) · [epa-repowering-brownfield-to-solar-site-finder](https://apify.com/malonestar/epa-repowering-brownfield-to-solar-site-finder) · [epa-sole-source-aquifer-screener](https://apify.com/malonestar/epa-sole-source-aquifer-screener) · [epa-tri-facility-release-rollup](https://apify.com/malonestar/epa-tri-facility-release-rollup) · [epa-tsca-cdr-chemical-site-screener](https://apify.com/malonestar/epa-tsca-cdr-chemical-site-screener) · [erns-nrc-release-incident-screener](https://apify.com/malonestar/erns-nrc-release-incident-screener) · [fuds-defense-site-screener](https://apify.com/malonestar/fuds-defense-site-screener) · [historic-land-use-sic-contaminant-screener](https://apify.com/malonestar/historic-land-use-sic-contaminant-screener) · [site-due-diligence-bundle](https://apify.com/malonestar/site-due-diligence-bundle) · [state-tank-spill-registry-screener](https://apify.com/malonestar/state-tank-spill-registry-screener) · [usgs-historical-topo-records-review](https://apify.com/malonestar/usgs-historical-topo-records-review)
 
 **Flood, fire, quake & ground hazard** (13)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gov-data-mcp",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "mcpName": "io.github.malonestar/gov-data-mcp",
   "description": "MCP server exposing published US government open-data tools (EPA, FEMA, USGS, NOAA, FAA, USACE, FDIC, HUD, state licensing boards) as agent-callable tools, backed by Apify Actors.",
   "type": "module",
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "test": "node --test test/tools.test.js test/apify.test.js test/catalog.test.js test/agent-surface.test.js test/presets.test.js",
+    "test": "node --test test/tools.test.js test/apify.test.js test/catalog.test.js test/agent-surface.test.js test/presets.test.js test/guidance.test.js",
     "catalog": "node tools/gen-catalog.cjs",
     "check:catalog": "node tools/check-catalog-live.cjs",
     "readme": "node tools/gen-readme-coverage.cjs"