@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/src/server.ts

@@ -55,8 +55,18 @@ import * as nsf from "./nsf.js";
 import * as clinicaltrials from "./clinicaltrials.js";
 import * as census from "./census.js";
 import * as censusEconomic from "./census-economic.js";
+import * as epaEnvirofacts from "./epa-envirofacts.js";
+import * as cmsUtilization from "./cms-utilization.js";
+import * as cmsHospital from "./cms-hospital.js";
+import * as cmsFacility from "./cms-facility.js";
+import * as cmsSupplier from "./cms-supplier.js";
 import * as fred from "./fred.js";
+import * as bea from "./bea.js";
 import * as gsaPerdiem from "./gsa-perdiem.js";
+import * as dol from "./dol.js";
+import * as lda from "./lda.js";
+import * as courtlistener from "./courtlistener.js";
+import * as nonprofit from "./nonprofit.js";
 import * as fema from "./fema.js";
 import * as fdic from "./fdic.js";
 import * as bls from "./bls.js";
@@ -66,6 +76,10 @@ import * as nppes from "./nppes.js";
 import * as cms from "./cms.js";
 import * as fac from "./fac.js";
 import * as usitc from "./usitc.js";
+import * as openfda from "./openfda.js";
+import * as openfdaDevice from "./openfda-device.js";
+import * as nhtsa from "./nhtsa.js";
+import * as cpsc from "./cpsc.js";
 import { fetchAttachmentText } from "./attachments.js";
 import * as keys from "./keys.js";
 import { toToolError, ToolErrorCarrier, errorFromResponse } from "./errors.js";
@@ -81,7 +95,7 @@ import { realpathSync } from "node:fs";
 const SERVER_NAME = "mcp-sam-gov";
 // Kept in lockstep with package.json / manifest.json / server.json.
 // Keep in sync with package.json "version" (asserted at release; see CHANGELOG).
-const SERVER_VERSION = "1.2.0";
+const SERVER_VERSION = "1.4.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -3424,6 +3438,290 @@ const CensusBusinessPatternsInput = z.object({
     ),
 });
 
+// ─── EPA Envirofacts TRI facilities (ADR-0059) — keyless, PATH-segment SSRF ──
+// data.epa.gov /efservice/tri_facility. Two requests: a count sub-query for the
+// EXACT total (P1) + the data slice. All user values ride as PATH SEGMENTS, so each
+// is charclass-validated + encodeURIComponent-encoded (the load-bearing SSRF guard).
+const EpaTriFacilitiesInput = z
+  .object({
+    state: z
+      .string()
+      .regex(/^[A-Za-z]{2}$/)
+      .optional()
+      .describe(
+        "A 2-letter US state/territory code, e.g. 'VA', 'CA', 'PR' (→ state_abbr; case-insensitive). Provide at least this OR `facilityName`. Validated ^[A-Za-z]{2}$ (it rides in the request path).",
+      ),
+    facilityName: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(/^[A-Za-z0-9 &.\-]+$/)
+      .optional()
+      .describe(
+        "A partial facility-name match (→ facility_name/CONTAINING/…; case-insensitive), e.g. 'chemical', 'boeing'. Provide at least this OR `state`. Allowed: letters/digits/space/& - . (≤100 chars); '/' and '..' rejected (path-injection guard).",
+      ),
+    county: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(/^[A-Za-z0-9 &.\-]+$/)
+      .optional()
+      .describe(
+        "A partial county-name match (→ county_name/CONTAINING/…), e.g. 'FAIRFAX'. Optional additional filter; same charclass as facilityName.",
+      ),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("Max facilities to return (1–100, default 25). Offset-paginated."),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+  })
+  .refine((v) => v.state !== undefined || v.facilityName !== undefined, {
+    message: "Provide at least `state` or `facilityName` (an all-empty query would scan the whole national TRI table and is refused).",
+    path: ["state"],
+  });
+
+// ─── CMS Medicare provider-service utilization (ADR-0061) — keyless, two-request ──
+// data.cms.gov /data-api/v1/dataset/{uuid}. Two requests: a stats count sub-query
+// for the EXACT total (P1 — found_rows) + the data slice (a bare JSON array). Filter
+// VALUES ride via URLSearchParams (bracket key + value encoded). REQUIRE npi OR
+// state (the 9.78M-row table is never scanned unscoped).
+const CmsMedicareProviderServicesInput = z
+  .object({
+    npi: z
+      .string()
+      .regex(/^\d{10}$/)
+      .optional()
+      .describe(
+        "A 10-digit National Provider Identifier (→ Rndrng_NPI), e.g. '1003000126'. Provide at least this OR `state`. Validated ^\\d{10}$.",
+      ),
+    state: z
+      .string()
+      .regex(/^[A-Za-z]{2}$/)
+      .optional()
+      .describe(
+        "A 2-letter US state/territory code (→ Rndrng_Prvdr_State_Abrvtn), e.g. 'VA', 'CA'. Provide at least this OR `npi`. Validated ^[A-Za-z]{2}$.",
+      ),
+    providerType: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(/^[A-Za-z0-9 &.,()/'-]+$/)
+      .optional()
+      .describe(
+        "An optional specialty filter matching the CMS provider type EXACTLY (→ Rndrng_Prvdr_Type), e.g. 'Family Practice', 'Physical Therapist in Private Practice'. Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars).",
+      ),
+    hcpcsCode: z
+      .string()
+      .regex(/^[A-Za-z0-9]{1,10}$/)
+      .optional()
+      .describe(
+        "An optional HCPCS/CPT service code filter (→ HCPCS_Cd), e.g. '97110', 'G0463'. Validated ^[A-Za-z0-9]{1,10}$.",
+      ),
+    size: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("Max provider-service rows to return (1–100, default 25). Offset-paginated."),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+  })
+  .refine((v) => v.npi !== undefined || v.state !== undefined, {
+    message: "Provide at least `npi` or `state` (an all-empty query would scan the entire 9.78M-row Medicare utilization table and is refused; providerType/hcpcsCode alone are not enough to scope).",
+    path: ["npi"],
+  });
+
+// ─── CMS Hospital Compare "Hospital General Information" (ADR-0062) — keyless ──
+// data.cms.gov /provider-data/api/1/datastore/query/{datasetId}/0. A SINGLE request:
+// the response's top-level `count` is the EXACT per-filter total (P1). Filters ride
+// as DKAN conditions[] triples via URLSearchParams (bracket key + value encoded).
+// REQUIRE state OR facilityName (the ~5,432-hospital table is never scanned unscoped).
+const CmsHospitalCompareInput = z
+  .object({
+    state: z
+      .string()
+      .regex(/^[A-Za-z]{2}$/)
+      .optional()
+      .describe(
+        "A 2-letter US state/territory code (→ state, EXACT match), e.g. 'VA', 'CA'. Provide at least this OR `facilityName`. Validated ^[A-Za-z]{2}$.",
+      ),
+    facilityName: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(/^[A-Za-z0-9 &.,()/'-]+$/)
+      .optional()
+      .describe(
+        "A hospital-name fragment (→ facility_name, case-insensitive SUBSTRING/contains match), e.g. 'children'. Provide at least this OR `state`. Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars).",
+      ),
+    hospitalType: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(/^[A-Za-z0-9 &.,()/'-]+$/)
+      .optional()
+      .describe(
+        "An optional hospital-type filter (→ hospital_type, case-insensitive SUBSTRING/contains match), e.g. 'Acute', 'Critical Access'. Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars).",
+      ),
+    size: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("Max hospital rows to return (1–100, default 25). Offset-paginated."),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+  })
+  .refine((v) => v.state !== undefined || v.facilityName !== undefined, {
+    message: "Provide at least `state` or `facilityName` (an all-empty query would scan the entire ~5,432-hospital table and is refused; hospitalType alone is not enough to scope).",
+    path: ["state"],
+  });
+
+// ─── CMS Facility Directory (data.cms.gov provider-data, ADR-0063) — KEYLESS ──
+// A four-dataset facility directory generalizing cms_hospital_compare beyond
+// hospitals. `facilityType` is a Zod ENUM that indexes a MODULE-CONSTANT map to a
+// VETTED dataset id (nursing_home → 4pq5-n9py, home_health → 6jpm-sxkc, hospice →
+// yc9t-dgbk, dialysis → 23ew-n7w9) — the user value never enters the URL path. A
+// SINGLE request: the response's top-level `count` is the EXACT per-filter total
+// (P1). Filters ride as DKAN conditions[] triples via URLSearchParams. name/address/
+// ownership columns vary per dataset → coalesced (null if none).
+const CmsFacilityDirectoryInput = z.object({
+  facilityType: z
+    .enum(["nursing_home", "home_health", "hospice", "dialysis"])
+    .describe(
+      "REQUIRED — which CMS provider-data dataset to search: 'nursing_home' (~14,695), 'home_health' (~12,460), 'hospice' (~6,852), or 'dialysis' (~7,490). Selects the dataset id via a constant map (the value never enters the URL path).",
+    ),
+  state: z
+    .string()
+    .regex(/^[A-Za-z]{2}$/)
+    .optional()
+    .describe(
+      "An optional 2-letter US state/territory code (→ state, EXACT match), e.g. 'VA', 'TX'. Validated ^[A-Za-z]{2}$.",
+    ),
+  facilityName: z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[A-Za-z0-9 &.,()/'-]+$/)
+    .optional()
+    .describe(
+      "An optional facility-name fragment (case-insensitive SUBSTRING/contains match against the dataset's primary-name column). Allowed: letters/digits/space/& . , ( ) / ' - (≤100 chars).",
+    ),
+  size: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Max facility rows to return (1–100, default 25). Offset-paginated."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+
+// ─── CMS DMEPOS by Supplier (data.cms.gov data-API, ADR-0064) — KEYLESS ──
+// SAME host/endpoint/two-request-stats-count pattern as cms_medicare_provider_services.
+// REQUIRE npi OR state (the supplier table is never scanned unscoped). Filter VALUES
+// ride as URLSearchParams filter[Col]=Val (bracket key + value encoded — the SSRF guard).
+const CmsDmeposSuppliersInput = z
+  .object({
+    npi: z
+      .string()
+      .regex(/^\d{10}$/)
+      .optional()
+      .describe(
+        "A 10-digit supplier National Provider Identifier (→ Suplr_NPI), e.g. '1003000126'. Provide at least this OR `state`. Validated ^\\d{10}$.",
+      ),
+    state: z
+      .string()
+      .regex(/^[A-Za-z]{2}$/)
+      .optional()
+      .describe(
+        "A 2-letter US state/territory code (→ Suplr_Prvdr_State_Abrvtn), e.g. 'VA', 'CA'. Provide at least this OR `npi`. Validated ^[A-Za-z]{2}$.",
+      ),
+    size: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("Max supplier rows to return (1–100, default 25). Offset-paginated."),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+  })
+  .refine((v) => v.npi !== undefined || v.state !== undefined, {
+    message: "Provide at least `npi` or `state` (an all-empty query would scan the entire DMEPOS supplier table and is refused).",
+    path: ["npi"],
+  });
+
+// ─── CMS Revoked Medicare Providers & Suppliers (data.cms.gov data-API, ADR-0064) ──
+// KEYLESS. A legally-published revocation/exclusion register (~7,059 rows) — the same
+// vetting class as the OFAC / SAM exclusion lists. ALL filters optional (small table —
+// pagination is fine unfiltered). SAME two-request stats-count P1 pattern.
+const CmsRevokedProvidersInput = z.object({
+  npi: z
+    .string()
+    .regex(/^\d{10}$/)
+    .optional()
+    .describe(
+      "An optional 10-digit National Provider Identifier (→ NPI), e.g. '1003000126'. Validated ^\\d{10}$.",
+    ),
+  state: z
+    .string()
+    .regex(/^[A-Za-z]{2}$/)
+    .optional()
+    .describe(
+      "An optional 2-letter US state/territory code (→ STATE_CD, EXACT match), e.g. 'FL', 'CA'. Validated ^[A-Za-z]{2}$.",
+    ),
+  lastName: z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[A-Za-z0-9 .,'-]+$/)
+    .optional()
+    .describe(
+      "An optional last-name filter (→ LAST_NAME, EXACT match). Allowed: letters/digits/space/. , ' - (≤100 chars).",
+    ),
+  size: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Max revocation rows to return (1–100, default 25). Offset-paginated."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+
 // ─── FRED (Federal Reserve Economic Data) — the SECOND key-required source ──
 // ADR-0048. Macro context (GDP/CPI/rates/unemployment/PPI). REQUIRES a free
 // FRED_API_KEY; without it both tools throw an honest config error (the other 112
@@ -3486,6 +3784,239 @@ const FredSeriesObservationsInput = z.object({
     .describe("Observation date order: 'asc' (oldest first, FRED default) or 'desc' (newest first)."),
 });
 
+// ─── openFDA recall/enforcement (api.fda.gov) — KEYLESS + OPTIONAL rate-limit key ──
+// ADR-0054. Drug/device/food recall enforcement records. Structured filters ONLY
+// (no raw Lucene passthrough — injection-safe); the tool assembles the openFDA
+// `search=` string with proper escaping. totalAvailable = meta.results.total (P1);
+// a no-match query (openFDA HTTP 404 NOT_FOUND) ⇒ an honest empty (P2). An OPTIONAL
+// OPENFDA_API_KEY only raises the rate limit (keyless works ~1000/day).
+const OpenfdaEnforcementInput = z.object({
+  category: z
+    .enum(["drug", "device", "food"])
+    .optional()
+    .describe(
+      "The recall category (default 'drug'): 'drug', 'device', or 'food'. Selects the openFDA /{category}/enforcement endpoint.",
+    ),
+  firm: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Recalling firm name filter (→ recalling_firm), e.g. 'pfizer'. Matched as an escaped Lucene phrase.",
+    ),
+  product: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Product description filter (→ product_description), e.g. 'insulin'. Matched as an escaped Lucene phrase.",
+    ),
+  reason: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Reason-for-recall filter (→ reason_for_recall), e.g. 'contamination'. Matched as an escaped Lucene phrase.",
+    ),
+  classification: z
+    .enum(["Class I", "Class II", "Class III"])
+    .optional()
+    .describe(
+      "FDA recall classification filter: 'Class I' (most serious), 'Class II', or 'Class III'.",
+    ),
+  status: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Recall status filter (→ status), e.g. 'Ongoing', 'Terminated', 'Completed'.",
+    ),
+  state: z
+    .string()
+    .regex(/^[A-Za-z]{2}$/)
+    .optional()
+    .describe(
+      "2-letter US state/territory postal code filter (→ state), e.g. 'CA'. Validated ^[A-Za-z]{2}$.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Max recall records to return (default 25, max 100). Offset-paginated via skip."),
+  skip: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+
+// ─── openFDA 510(k) device clearances (api.fda.gov) — KEYLESS + OPTIONAL rate-limit key ──
+// ADR-0056. FDA premarket-notification (510(k)) device clearances — SAME source/envelope/
+// crux as openfda_enforcement (structured filters ONLY — the tool assembles + escapes the
+// search= string, injection-safe). totalAvailable = meta.results.total (P1); a no-match
+// query (openFDA HTTP 404 NOT_FOUND) ⇒ an honest empty (P2). An OPTIONAL OPENFDA_API_KEY
+// only raises the rate limit (keyless works ~1000/day).
+const OpenfdaDeviceClearancesInput = z.object({
+  applicant: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Applicant / manufacturer name filter (→ applicant), e.g. 'medtronic'. Matched as an escaped Lucene phrase.",
+    ),
+  deviceName: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Device name filter (→ device_name), e.g. 'catheter'. Matched as an escaped Lucene phrase.",
+    ),
+  productCode: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "FDA product code filter (→ product_code), e.g. 'DXN'. Matched as an escaped Lucene phrase.",
+    ),
+  clearanceType: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "510(k) clearance type filter (→ clearance_type), e.g. 'Traditional', 'Special', 'Abbreviated'. Matched as an escaped Lucene phrase.",
+    ),
+  kNumber: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "510(k) clearance number (K-number) filter (→ k_number), e.g. 'K123456'. Matched as an escaped Lucene phrase.",
+    ),
+  state: z
+    .string()
+    .regex(/^[A-Za-z]{2}$/)
+    .optional()
+    .describe(
+      "2-letter US state/territory postal code filter (→ state), e.g. 'CA'. Validated ^[A-Za-z]{2}$.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Max clearance records to return (default 25, max 100). Offset-paginated via skip."),
+  skip: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+
+// ─── NHTSA vehicle safety (api.nhtsa.gov) — KEYLESS vehicle/parts supplier vetting ──
+// ADR-0057. Two tools (recalls + complaints) share make/model/modelYear inputs. NO
+// API key at all. ★The complaints VIN (PII) is excluded from the output. modelYear is
+// ^\d{4}$; make/model are letters/digits/space/hyphen only (SSRF/injection guard).
+const NhtsaVehicleInput = z.object({
+  make: z
+    .string()
+    .regex(/^[A-Za-z0-9 -]+$/)
+    .describe(
+      "Vehicle make (required), e.g. 'honda', 'ford'. Letters/digits/space/hyphen only (^[A-Za-z0-9 -]+$).",
+    ),
+  model: z
+    .string()
+    .regex(/^[A-Za-z0-9 -]+$/)
+    .describe(
+      "Vehicle model (required), e.g. 'accord', 'f-150'. Letters/digits/space/hyphen only (^[A-Za-z0-9 -]+$).",
+    ),
+  modelYear: z
+    .string()
+    .regex(/^\d{4}$/)
+    .describe("4-digit model year (required), e.g. '2020'. Validated ^\\d{4}$."),
+});
+
+// ─── CPSC consumer-product recalls (www.saferproducts.gov) — KEYLESS goods/import vetting ──
+// ADR-0058. One tool. NO API key at all. The response is a bare JSON ARRAY with no
+// total-count field / no pagination (totalAvailable = the returned count). All filters
+// optional; with NO filter the tool defaults RecallDateStart to ~90 days ago (disclosed)
+// rather than fetch the whole dataset. dates are ^\d{4}-\d{2}-\d{2}$; recallNumber is
+// letters/digits/hyphen only (SSRF/injection guard).
+const CpscRecallsInput = z.object({
+  dateStart: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe(
+      "Recall date range START (optional), YYYY-MM-DD, e.g. '2025-01-01' (→ RecallDateStart). Validated ^\\d{4}-\\d{2}-\\d{2}$.",
+    ),
+  dateEnd: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe(
+      "Recall date range END (optional), YYYY-MM-DD, e.g. '2025-01-31' (→ RecallDateEnd). Validated ^\\d{4}-\\d{2}-\\d{2}$.",
+    ),
+  productName: z
+    .string()
+    .optional()
+    .describe("Product name substring filter (optional), e.g. 'helmet' (→ ProductName)."),
+  manufacturer: z
+    .string()
+    .optional()
+    .describe("Manufacturer name substring filter (optional) (→ Manufacturer)."),
+  recallNumber: z
+    .string()
+    .regex(/^[A-Za-z0-9-]+$/)
+    .optional()
+    .describe(
+      "A specific CPSC recall number (optional), e.g. '25088' (→ RecallNumber). Letters/digits/hyphen only (^[A-Za-z0-9-]+$).",
+    ),
+});
+
+// ─── BEA Regional Economic Accounts (apps.bea.gov) — the THIRD key-required source ──
+// ADR-0051. County/state/MSA GDP-by-industry (CAGDP2/SAGDP2N) + personal income
+// (CAINC1/SAINC1) — the regional/sub-national place-of-performance lane. REQUIRES a
+// free BEA_API_KEY; without it the tool throws an honest config error (the other 116
+// tools stay keyless). ★A missing/invalid key returns HTTP 200 with a
+// BEAAPI.Results.Error carrier (NOT an HTTP error), detected pre-drift. The key rides
+// UserID= ONLY. DataValue is a comma string; suppression codes ((NA)/(D)/…) → null.
+const BeaRegionalDataInput = z.object({
+  tableName: z
+    .string()
+    .regex(/^[A-Za-z0-9]{2,20}$/)
+    .describe(
+      "A BEA Regional table code (2–20 alphanumerics), e.g. 'CAGDP2' (county GDP by industry), 'SAGDP2N' (state GDP by industry), 'CAINC1'/'SAINC1' (personal income). Validated ^[A-Za-z0-9]{2,20}$. Required.",
+    ),
+  geoFips: z
+    .string()
+    .regex(/^[A-Za-z0-9]{2,10}$/)
+    .describe(
+      "The BEA GeoFips selector: 'STATE' (all states), a county FIPS like '06075', or an MSA code. Validated ^[A-Za-z0-9]{2,10}$. Required.",
+    ),
+  lineCode: z
+    .string()
+    .regex(/^([0-9]{1,4}|ALL)$/)
+    .describe(
+      "The industry/statistic line code — an integer (1–4 digits), e.g. '1', or 'ALL' for every line in the table. Validated ^([0-9]{1,4}|ALL)$. Required.",
+    ),
+  year: z
+    .string()
+    .regex(/^(\d{4}|LAST5|ALL)$/)
+    .optional()
+    .describe(
+      "The data year: a 4-digit year (e.g. '2022'), 'LAST5' (the latest 5 years, default), or 'ALL'. Validated ^(\\d{4}|LAST5|ALL)$.",
+    ),
+  frequency: z
+    .enum(["A", "Q"])
+    .optional()
+    .describe("Data frequency: 'A' (annual, default) or 'Q' (quarterly)."),
+});
+
 // ─── GSA Federal Travel Per-Diem (api.gsa.gov) — travel-cost lane ──
 // ADR-0050. Lodging + M&IE reimbursement ceilings by city/state OR zip for a year.
 // KEYLESS by default via the shared DEMO_KEY (datagovKey.ts seam); DATA_GOV_API_KEY
@@ -3525,6 +4056,234 @@ const GsaPerdiemRatesInput = z
     "Look up GSA per-diem rates by EITHER (city + state) OR zip. Supplying both, or neither, ⇒ invalid_input.",
   );
 
+// ─── US DOL Data API v4 (apiprod.dol.gov) — the labor-enforcement lane ──
+// ADR-0053. A DELIBERATE key split: dol_list_datasets (the CATALOG) is KEYLESS;
+// dol_get_dataset (the DATA endpoint) is the 4th REQUIRED key (DOL_API_KEY, no keyless
+// tier — throws pre-fetch without it). The key rides the X-API-KEY HEADER ONLY. The
+// data envelope is key-gated/unverified ⇒ records are surfaced verbatim + totalAvailable
+// defaults null (never `returned` faked as the total). agency/query filter is CLIENT-SIDE.
+const DolListDatasetsInput = z.object({
+  agency: z
+    .string()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe(
+      "CLIENT-SIDE filter by agency abbreviation (e.g. 'WHD', 'OSHA', 'ILAB', 'ETA') or a substring of the agency name. The DOL catalog API does not filter server-side, so this is applied to the fetched catalog.",
+    ),
+  query: z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe(
+      "CLIENT-SIDE free-text filter (substring over dataset name / description / category / table / endpoint), e.g. 'child labor', 'wage', 'inspection'.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Datasets to return per page (default 25, max 200). Offset-paginated over the (filtered) catalog."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+
+const DolGetDatasetInput = z.object({
+  agency: z
+    .string()
+    .regex(/^[A-Za-z0-9_]+$/)
+    .describe(
+      "The agency abbreviation (the `agencyAbbr` from dol_list_datasets), e.g. 'WHD', 'OSHA', 'ILAB'. Rides in the request PATH. Validated ^[A-Za-z0-9_]+$. Required.",
+    ),
+  table: z
+    .string()
+    .regex(/^[A-Za-z0-9_]+$/)
+    .describe(
+      "The dataset endpoint — the `apiUrl` field from dol_list_datasets (the DOL 'api_url', NOT the tablename), e.g. 'Child_Labor_Report__2016_to_2022'. Rides in the request PATH. Validated ^[A-Za-z0-9_]+$. Required.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Max records to return (default 10, max 100). Offset-paginated."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+  filterField: z
+    .string()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("Optional: a dataset field name to filter on (paired with filterValue → a DOL filter_object equality filter). Supply BOTH or NEITHER."),
+  filterValue: z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Optional: the value the filterField must equal. Supply BOTH filterField and filterValue, or NEITHER."),
+  fields: z
+    .array(z.string().min(1))
+    .optional()
+    .describe("Optional: best-effort column selection (a subset of field names to return). Not documented for v4; the API ignores or 400s an unsupported selection (surfaced honestly)."),
+});
+
+// ─── US Senate LDA lobbying filings (lda.senate.gov) — the lobbying/B2G lane ──
+// ADR-0052. Who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue.
+// KEYLESS (anonymous 200); an optional free LDA_API_KEY only raises the rate limit
+// and rides the Authorization: Token … header ONLY. `count` is the REAL total
+// (~1.95M) — never results.length; page-based pagination (page/pageSize ≤25). All
+// filter VALUES ride URLSearchParams; filingYear/page/pageSize charclass/range-guarded.
+const LdaSearchFilingsInput = z.object({
+  registrantName: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the registrant (the lobbying firm / in-house filer) name, e.g. 'Akin Gump'. Substring match, upstream-validated."),
+  clientName: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the client name (who the lobbying is FOR), e.g. 'Google'. Substring match, upstream-validated."),
+  lobbyistName: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by an individual lobbyist's name. Substring match, upstream-validated."),
+  filingYear: z
+    .string()
+    .regex(/^\d{4}$/)
+    .optional()
+    .describe("Filter by filing year, a 4-digit year (e.g. '2024'). Validated ^\\d{4}$."),
+  filingType: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the filing type short code (e.g. 'Q1' Q1 report, 'RR' registration, 'YE' year-end). A bad code ⇒ upstream HTTP 400 ⇒ invalid_input (surfaced)."),
+  agency: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the federal government entity lobbied (maps to government_entity — the B2G signal), e.g. 'DEPARTMENT OF DEFENSE'."),
+  issue: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Filter by the specific lobbying issues text (maps to filing_specific_lobbying_issues), e.g. 'appropriations'."),
+  page: z
+    .number()
+    .int()
+    .min(1)
+    .default(1)
+    .describe("1-based page number (default 1). Page with the next page number from _meta.notes / when _meta.pagination.hasMore."),
+  pageSize: z
+    .number()
+    .int()
+    .min(1)
+    .max(25)
+    .default(25)
+    .describe("Filings per page, 1..25 (the LDA API caps at 25), default 25."),
+});
+
+// ─── US federal court opinions (www.courtlistener.com) — the litigation lane ──
+// ADR-0055. Federal court decisions (opinions) — the judicial signal no contract/
+// spending/lobbying source carries (e.g. uscfc bid-protest / contract-claim opinions).
+// ★PROVENANCE: CourtListener (Free Law Project, a non-profit), NOT a .gov API —
+// PACER (the .gov source) is paywalled. KEYLESS (anonymous 200); an optional free
+// COURTLISTENER_API_TOKEN only raises the rate limit, riding the Authorization: Token
+// … header ONLY (the lda/socrata app-token lineage). `count` is the REAL total —
+// never results.length; CURSOR pagination (nextCursor extracted from `next`). court/
+// dates charclass-guarded; all filter VALUES ride URLSearchParams; type=o is FIXED.
+const CourtlistenerSearchOpinionsInput = z.object({
+  query: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Full-text query (maps to q), e.g. 'bid protest' or a party name. Matches across the opinion text/metadata."),
+  court: z
+    .string()
+    .regex(/^[a-z0-9]+$/)
+    .optional()
+    .describe("A CourtListener court id (lowercase alphanumerics ^[a-z0-9]+$), e.g. 'uscfc' (US Court of Federal Claims — contract claims/bid protests), 'cafc' (Federal Circuit — contract/patent appeals), 'scotus'."),
+  dateFiledAfter: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe("Only opinions filed on/after this ISO date (→ filed_after), e.g. '2020-01-01'. Validated ^\\d{4}-\\d{2}-\\d{2}$."),
+  dateFiledBefore: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe("Only opinions filed on/before this ISO date (→ filed_before), e.g. '2024-12-31'. Validated ^\\d{4}-\\d{2}-\\d{2}$."),
+  natureOfSuit: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Nature-of-suit text — folded into the q full-text query (the v4 opinions search has no verified dedicated filter), so it matches the text anywhere in the document (disclosed in _meta.notes)."),
+  cursor: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Opaque continuation token for the NEXT page — pass back the _meta.nextCursor from the previous response (CourtListener uses CURSOR pagination, not page/offset)."),
+  order: z
+    .string()
+    .min(1)
+    .default("dateFiled desc")
+    .describe("Sort order (maps to order_by), default 'dateFiled desc' (most recent first). E.g. 'dateFiled asc', 'score desc'."),
+});
+
+// ─── US tax-exempt nonprofits (projects.propublica.org) — the nonprofit lane ──
+// ADR-0060. IRS Form 990 public records republished KEYLESS by ProPublica Nonprofit
+// Explorer (a non-profit newsroom) — NOT a .gov API (the IRS has no clean query
+// API). ★PROVENANCE disclosed in _meta.source + a note. KEYLESS (no key of any
+// kind). search: q/state[id]/ntee[id]/page (0-based); total_results is the REAL
+// total — never organizations.length. All VALUES ride URLSearchParams (incl. the
+// bracket keys); state/ntee charclass/range-guarded.
+const NonprofitSearchInput = z.object({
+  query: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Full-text query (maps to q) — an organization name or keyword, e.g. 'american red cross'. Matches across the org name/metadata."),
+  state: z
+    .string()
+    .regex(/^[A-Za-z]{2}$/)
+    .optional()
+    .describe("Filter by a 2-letter US state/territory code (maps to state[id]), e.g. 'VA'. Validated ^[A-Za-z]{2}$."),
+  ntee: z
+    .number()
+    .int()
+    .min(1)
+    .max(10)
+    .optional()
+    .describe("Filter by NTEE major category, an integer 1..10 (maps to ntee[id]) — the National Taxonomy of Exempt Entities top-level group (e.g. 1 Arts, 3 Environment, 8 Health)."),
+  page: z
+    .number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe("0-BASED page number (default 0). Page with cur_page+1 from _meta.notes / when _meta.pagination.hasMore."),
+});
+
+// nonprofit_financials — one org's Form 990 profile + financials by EIN. KEYLESS.
+// ein rides the URL PATH ⇒ digits-only ^\d{1,9}$. An unknown EIN (404) ⇒ not_found.
+const NonprofitFinancialsInput = z.object({
+  ein: z
+    .string()
+    .regex(/^\d{1,9}$/)
+    .describe("The organization's EIN (Employer Identification Number), 1..9 digits, e.g. '530196605' (American National Red Cross). Validated ^\\d{1,9}$; rides the URL path."),
+});
+
 // api_key_status takes no input — it is a pure status query over process.env.
 const ApiKeyStatusInput = z.object({});
 
@@ -4993,17 +5752,97 @@ export const TOOLS: ToolDef[] = [
   // ━━━ US Census County Business Patterns — market sizing (1) ━━━ ADR-0047
   // ★The server's FIRST KEY-REQUIRED source: the Census Data API removed its
   // keyless tier, so WITHOUT a CENSUS_API_KEY this tool throws an honest
-  // invalid_input config error (the other 111 tools stay keyless). NAICS×geography
+  // invalid_input config error (most other tools are keyless — see api_key_status). NAICS×geography
   // establishments / employment / annual payroll — the demand-side market-sizing
   // lane. Census negative suppression sentinels (-999999999 …) map to null (never
   // a negative number / never 0). The 2D-array body is parsed by header name.
   defineTool({
     name: "census_business_patterns",
     description:
-      "Market sizing by NAICS × geography — establishments, employment, and annual payroll from the US Census County Business Patterns (CBP) API (api.census.gov/data/{year}/cbp). ★REQUIRES a free CENSUS_API_KEY: the Census Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://api.census.gov/data/key_signup.html; Census and FRED are the only key-required sources — every other tool is keyless). Input: optional `naics` (2–6 digit NAICS-2017, e.g. '5415'; omit to aggregate all sectors), `geography` (us|state|county, default us; county REQUIRES `state`), `state` (2-digit FIPS, e.g. '06'), `year` (default '2022'), optional `limit` (client-side top-N; CBP has no server pagination). Returns { rows:[{ name, geoId, naicsCode, naicsLabel, establishments, employees, annualPayrollUsd, state }] } + honest _meta. HONESTY: establishments/employees are integer counts and annualPayrollUsd is annual US dollars (×1000 from the source's $1,000-unit PAYANN); Census SUPPRESSED/withheld cells (large negative sentinels like -999999999) map to null — NEVER a negative number and NEVER 0 (a genuine 0 stays 0); geoId/naicsCode/state are STRINGS (leading zeros survive). CBP returns the COMPLETE geography set for the filter (no pagination) ⇒ totalAvailable = the row count, complete:true. A missing/invalid key ⇒ invalid_input (a 302 to the Missing-Key page); a header-only body ⇒ honest empty (returned:0); a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The key rides ONLY in the &key= query param — never logged or echoed.",
+      "Market sizing by NAICS × geography — establishments, employment, and annual payroll from the US Census County Business Patterns (CBP) API (api.census.gov/data/{year}/cbp). ★REQUIRES a free CENSUS_API_KEY: the Census Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://api.census.gov/data/key_signup.html; call api_key_status to see every source's key requirement). Input: optional `naics` (2–6 digit NAICS-2017, e.g. '5415'; omit to aggregate all sectors), `geography` (us|state|county, default us; county REQUIRES `state`), `state` (2-digit FIPS, e.g. '06'), `year` (default '2022'), optional `limit` (client-side top-N; CBP has no server pagination). Returns { rows:[{ name, geoId, naicsCode, naicsLabel, establishments, employees, annualPayrollUsd, state }] } + honest _meta. HONESTY: establishments/employees are integer counts and annualPayrollUsd is annual US dollars (×1000 from the source's $1,000-unit PAYANN); large-negative suppression sentinels map to null — NEVER a negative number and NEVER 0 (a genuine 0 stays 0; note CBP primarily uses noise-infusion + suppression flags, surfaced as reported — see the tool's suppression note); geoId/naicsCode/state are STRINGS (leading zeros survive). CBP returns the COMPLETE geography set for the filter (no pagination) ⇒ totalAvailable = the row count, complete:true. A missing/invalid key ⇒ invalid_input (a 302 to the Missing-Key page); a header-only body ⇒ honest empty (returned:0); a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The key rides ONLY in the &key= query param — never logged or echoed.",
     inputSchema: CensusBusinessPatternsInput,
     handler: (input) => censusEconomic.businessPatterns(input),
   }),
+  // ━━━ EPA Envirofacts TRI facilities — environmental footprint (1) ━━━ ADR-0059
+  // KEYLESS (data.epa.gov /efservice/tri_facility). ★Two requests: a count
+  // sub-query yields the EXACT total (P1 — TOTALQUERYRESULTS, e.g. VA=1247), then
+  // the data slice. All user values ride as PATH SEGMENTS → each is
+  // charclass-validated + encodeURIComponent-encoded (the load-bearing SSRF guard).
+  defineTool({
+    name: "epa_tri_facilities",
+    description:
+      "Look up EPA Toxics Release Inventory (TRI) reporting facilities by state / facility-name / county — an environmental-footprint / place-of-performance screen (EPA Envirofacts, keyless; data.epa.gov/efservice/tri_facility). Input: `state` (2-letter, e.g. 'VA'), `facilityName` (partial match, e.g. 'chemical'), `county` (partial match) — provide at least `state` OR `facilityName` (an all-empty query is refused); optional `limit` (1–100, default 25), `offset`. Returns { facilities:[{ triFacilityId, facilityName, streetAddress, city, county, state, zip, region, closed }] } + honest _meta. ★HONESTY: totalAvailable is the EXACT count from a SEPARATE count sub-query (…/count/JSON → TOTALQUERYRESULTS), NEVER the returned-rows length; if that count fails, totalAvailable is null + a disclosing note (never length-faked). offset/limit pagination (hasMore = offset+returned < total). `closed` normalizes fac_closed_ind ('0'/'N'→false, '1'/'Y'→true, unrecognized→null — never a fabricated false); addresses/names are null-never-empty-string. A genuine no-match ⇒ honest empty (returned:0); a 4xx ⇒ invalid_input/not_found; a 5xx ⇒ THROWS; a 200 non-array/non-JSON ⇒ schema_drift. These are nominal TRI reporters, NOT a compliance/enforcement determination. KEYLESS — no key is sent.",
+    inputSchema: EpaTriFacilitiesInput,
+    handler: (input) => epaEnvirofacts.triFacilities(input),
+  }),
+  // ━━━ CMS Medicare provider-service utilization — healthcare market (1) ━━━ ADR-0061
+  // KEYLESS (data.cms.gov /data-api/v1/dataset/{uuid}). ★Two requests: a stats
+  // count sub-query yields the EXACT per-filter total (P1 — found_rows, e.g.
+  // VA=278254), then the data slice (a bare JSON array). All filter VALUES ride via
+  // URLSearchParams (bracket key + value encoded — the SSRF guard). REQUIRE npi OR
+  // state (the 9.78M-row table is never scanned unscoped). The dataset UUID is a
+  // SPECIFIC ANNUAL VINTAGE (surfaced in a _meta note; update yearly).
+  defineTool({
+    name: "cms_medicare_provider_services",
+    description:
+      "Look up Medicare Part-B provider utilization — for a given provider (NPI) or state, the HCPCS services rendered, beneficiaries served, and submitted / Medicare-allowed / Medicare-paid amounts (CMS 'Medicare Physician & Other Practitioners — by Provider and Service', keyless; data.cms.gov data-API). The demand-side complement to nppes_lookup_provider (who providers ARE → what they BILL) for healthcare-market / competitor / teaming due-diligence. Input: `npi` (10-digit) OR `state` (2-letter) — at least ONE is REQUIRED (the table is 9.78M rows; an all-empty query is refused; providerType/hcpcsCode alone are NOT enough to scope); optional `providerType` (exact CMS specialty, e.g. 'Family Practice'), `hcpcsCode` (e.g. '97110', 'G0463'), `size` (1–100, default 25), `offset`. Returns { services:[{ npi, providerName, credentials, providerType, city, state, zip, hcpcsCode, hcpcsDescription, totalBeneficiaries, totalServices, avgSubmittedCharge, avgMedicareAllowed, avgMedicarePayment }] } + honest _meta. ★HONESTY: totalAvailable is the EXACT count from a SEPARATE stats sub-query (…/data-viewer/stats → found_rows, e.g. VA=278254), NEVER the returned-rows length; if that count fails, totalAvailable is null + a disclosing note (never length-faked). offset/size pagination (hasMore = offset+returned < total). Aggregate/payment values are numeric-string → number|null (a genuine 0 stays 0, absent → null, never 0-faked); NPI/HCPCS/names are null-never-empty-string. A genuine no-match ⇒ honest empty (returned:0); a 4xx ⇒ invalid_input/not_found; a 5xx ⇒ THROWS; a 200 non-array/non-JSON ⇒ schema_drift. These are public PROVIDER-level AGGREGATE figures (no patient identifiers) for ONE annual vintage (the dataset year is disclosed in _meta) — a utilization snapshot, NOT a fraud/quality/fitness determination. KEYLESS — no key is sent.",
+    inputSchema: CmsMedicareProviderServicesInput,
+    handler: (input) => cmsUtilization.providerServices(input),
+  }),
+  // ━━━ CMS Hospital Compare — Hospital General Information (1) ━━━ ADR-0062
+  // KEYLESS (data.cms.gov /provider-data/api/1/datastore/query/{datasetId}). A
+  // SINGLE request: the response's top-level `count` is the EXACT per-filter total
+  // (P1 — VA=96), never the slice length. Filters ride as DKAN conditions[] triples
+  // via URLSearchParams (bracket key + value encoded — the SSRF guard): state is an
+  // EXACT match, facilityName/hospitalType are case-insensitive substring matches,
+  // AND-combined server-side. REQUIRE state OR facilityName (never scanned unscoped).
+  defineTool({
+    name: "cms_hospital_compare",
+    description:
+      "Look up Medicare-certified hospitals by US state and/or facility-name fragment — location, type, ownership, emergency-services flag, and CMS star rating (CMS Hospital Compare 'Hospital General Information', keyless; data.cms.gov provider-data datastore-query API, ~5,432 hospitals). A healthcare-facility directory / market-map lane (WHERE hospitals are and HOW CMS rates them). Input: `state` (2-letter, EXACT) OR `facilityName` (a name fragment, case-insensitive substring/contains match) — at least ONE is REQUIRED (an all-empty query is refused; hospitalType alone is NOT enough to scope); optional `hospitalType` (substring, e.g. 'Acute', 'Critical Access'), `size` (1–100, default 25), `offset`. Returns { hospitals:[{ facilityId, facilityName, address, city, state, zip, county, phone, hospitalType, ownership, emergencyServices, overallRating }] } + honest _meta. ★HONESTY: totalAvailable is the response's EXACT top-level `count` for the filter set (VA=96), NEVER the returned-rows length; offset/size pagination (hasMore = offset+returned < count). overallRating is CMS's 1–5 star rating as a number; 'Not Available'/blank/non-numeric ⇒ null (NEVER 0). emergencyServices normalizes 'Yes'⇒true / 'No'⇒false / else null (never a fabricated false). IDs/names/addresses are null-never-empty-string. A genuine no-match ⇒ honest empty (returned:0); a 4xx ⇒ invalid_input/not_found; a 5xx ⇒ THROWS; a 200 non-array body or one missing count/results ⇒ schema_drift. Filters are applied SERVER-SIDE (AND-combined) — nothing is silently dropped. This is a summary star rating, NOT a clinical-quality or fitness determination. KEYLESS — no key is sent.",
+    inputSchema: CmsHospitalCompareInput,
+    handler: (input) => cmsHospital.hospitalCompare(input),
+  }),
+  // ━━━ CMS Facility Directory — 4 provider-data datasets (1) ━━━ ADR-0063
+  // KEYLESS (data.cms.gov /provider-data/api/1/datastore/query/{datasetId}). A
+  // generalization of cms_hospital_compare beyond hospitals: facilityType (a Zod
+  // enum) indexes a CONSTANT map to a VETTED dataset id — the user value never enters
+  // the path (the load-bearing SSRF guard). A SINGLE request: the response's top-level
+  // `count` is the EXACT per-filter total (P1). name/address/ownership columns vary
+  // per dataset → coalesced (null if none — never empty-string, never fabricated).
+  defineTool({
+    name: "cms_facility_directory",
+    description:
+      "Look up Medicare/Medicaid-certified healthcare FACILITIES by type — nursing homes, home health agencies, hospices, or dialysis facilities — with their name, address, city, state, zip, and ownership (CMS provider-data, keyless; data.cms.gov datastore-query API, four datasets). A healthcare-facility directory / market-map lane that generalizes cms_hospital_compare beyond hospitals. Input: `facilityType` (REQUIRED enum — 'nursing_home' ~14,695 / 'home_health' ~12,460 / 'hospice' ~6,852 / 'dialysis' ~7,490; selects the dataset id via a constant map, the value never enters the URL path), optional `state` (2-letter, EXACT), `facilityName` (a name fragment, case-insensitive substring/contains match against the dataset's primary-name column), `size` (1–100, default 25), `offset`. Returns { facilities:[{ name, address, city, state, zip, facilityType, ownership }] } + honest _meta. ★HONESTY: totalAvailable is the response's EXACT top-level `count` for the filter set, NEVER the returned-rows length; offset/size pagination (hasMore = offset+returned < count). name/address/ownership column names DIFFER across the four datasets, so each is COALESCED over per-dataset candidates (name: provider_name/facility_name/legal_business_name; address: address/provider_address/address_line_1; ownership: ownership_type/type_of_ownership/profit_or_nonprofit) — a field absent in the chosen dataset is null (unknown), NEVER an empty string and NEVER fabricated. facilityType is echoed on each row. A genuine no-match ⇒ honest empty (returned:0); an invalid facilityType ⇒ invalid_input (blocked by the enum); a 4xx ⇒ invalid_input/not_found; a 5xx ⇒ THROWS; a 200 non-array body or one missing count/results ⇒ schema_drift. Filters are applied SERVER-SIDE (AND-combined) — nothing is silently dropped. This is a facility directory, NOT a clinical-quality or fitness determination. KEYLESS — no key is sent.",
+    inputSchema: CmsFacilityDirectoryInput,
+    handler: (input) => cmsFacility.facilityDirectory(input),
+  }),
+  // ━━━ CMS DMEPOS by Supplier — supply-side utilization (1) ━━━ ADR-0064
+  // KEYLESS (data.cms.gov /data-api/v1/dataset/{uuid}). ★Two requests: a stats count
+  // sub-query yields the EXACT per-filter total (P1 — found_rows), then the data slice
+  // (a bare JSON array). All filter VALUES ride via URLSearchParams (bracket key +
+  // value encoded — the SSRF guard). REQUIRE npi OR state (the supplier table is never
+  // scanned unscoped). The dataset UUID is a SPECIFIC ANNUAL VINTAGE (update yearly).
+  defineTool({
+    name: "cms_dmepos_suppliers",
+    description:
+      "Look up Medicare DMEPOS (Durable Medical Equipment, Devices & Supplies) SUPPLIERS — for a given supplier (NPI) or state, the supplier's identity plus aggregate Medicare figures: HCPCS codes billed, beneficiaries served, claims, services, and submitted / Medicare-allowed / Medicare-paid amounts (CMS 'Medicare DMEPOS — by Supplier', keyless; data.cms.gov data-API). The supply-side complement to cms_medicare_provider_services for healthcare-market / competitor / teaming due-diligence on equipment suppliers. Input: `npi` (10-digit) OR `state` (2-letter) — at least ONE is REQUIRED (an all-empty query is refused; the supplier table is never scanned unscoped); optional `size` (1–100, default 25), `offset`. Returns { suppliers:[{ npi, supplierName, credentials, entityType, city, state, zip, totalHcpcsCodes, totalBeneficiaries, totalClaims, totalServices, submittedCharges, medicareAllowed, medicarePayment }] } + honest _meta. ★HONESTY: totalAvailable is the EXACT count from a SEPARATE stats sub-query (…/data-viewer/stats → found_rows), NEVER the returned-rows length; if that count fails, totalAvailable is null + a disclosing note (never length-faked). offset/size pagination (hasMore = offset+returned < total). Aggregate/payment values are numeric-string → number|null (a genuine 0 stays 0, absent → null, never 0-faked); NPI/entityType/names are null-never-empty-string; supplierName joins Last_Name_Org + First_Name ('Last, First' for individuals, the org name alone for organizations). A genuine no-match ⇒ honest empty (returned:0); a 4xx ⇒ invalid_input/not_found; a 5xx ⇒ THROWS; a 200 non-array/non-JSON ⇒ schema_drift. These are public SUPPLIER-level AGGREGATE figures (no patient identifiers) for ONE annual vintage (disclosed in _meta) — a utilization snapshot, NOT a fraud/quality/fitness determination. KEYLESS — no key is sent.",
+    inputSchema: CmsDmeposSuppliersInput,
+    handler: (input) => cmsSupplier.dmeposSuppliers(input),
+  }),
+  // ━━━ CMS Revoked Medicare Providers & Suppliers — vetting/exclusion list (1) ━━━ ADR-0064
+  // KEYLESS (data.cms.gov /data-api/v1/dataset/{uuid}). A legally-published
+  // revocation/exclusion register (~7,059 rows) — the SAME vetting class as the OFAC /
+  // SAM exclusion lists already shipped (surfacing the names IS the point). ALL filters
+  // optional (small table — pagination is fine unfiltered). SAME two-request stats-count
+  // P1 pattern; filter VALUES ride via URLSearchParams (bracket key + value encoded).
+  defineTool({
+    name: "cms_revoked_providers",
+    description:
+      "Search CMS's PUBLIC 'Revoked Medicare Providers & Suppliers' list — the legally-published register of Medicare enrollment revocations, with the revoked provider/supplier's identity, provider type, revocation reason, effective date, and re-enrollment-bar expiration (CMS 'Revoked Providers and Suppliers', keyless; data.cms.gov data-API, ~7,059 rows). A vetting / due-diligence lane in the SAME class as the OFAC / SAM-exclusions lists — for screening a counterparty before teaming or subcontracting. Input (ALL optional — the ~7K-row list is safe to page unfiltered): `npi` (10-digit → NPI), `state` (2-letter → STATE_CD, exact), `lastName` (→ LAST_NAME, exact), `size` (1–100, default 25), `offset`. Returns { revocations:[{ enrollmentId, npi, name, state, providerType, revocationReason, revocationEffectiveDate, reenrollmentBarExpiration }] } + honest _meta (which notes this is CMS's public revocation/exclusion list — a due-diligence signal, NOT a current-eligibility, guilt, or fitness determination). ★HONESTY: totalAvailable is the EXACT count from a SEPARATE stats sub-query (…/data-viewer/stats → found_rows), NEVER the returned-rows length; if that count fails, totalAvailable is null + a disclosing note (never length-faked). offset/size pagination (hasMore = offset+returned < total). name coalesces ORG_NAME (organizations) else FIRST_NAME + LAST_NAME (individuals) — null if none, never a fabricated empty; NPI/reasons/dates are strings (null-never-empty-string). A genuine no-match ⇒ honest empty (returned:0); a 4xx ⇒ invalid_input/not_found; a 5xx ⇒ THROWS; a 200 non-array/non-JSON ⇒ schema_drift. KEYLESS — no key is sent.",
+    inputSchema: CmsRevokedProvidersInput,
+    handler: (input) => cmsSupplier.revokedProviders(input),
+  }),
   // ━━━ FRED (Federal Reserve Economic Data) — macro context (2) ━━━ ADR-0048
   // ★The server's SECOND KEY-REQUIRED source: FRED has NO keyless tier, so WITHOUT
   // a FRED_API_KEY both tools throw an honest invalid_input config error (the other
@@ -5012,7 +5851,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "fred_search_series",
     description:
-      "Discover FRED economic series (GDP, CPI, interest rates, unemployment, PPI…) by free-text search (FRED /fred/series/search; api.stlouisfed.org). ★REQUIRES a free FRED_API_KEY: FRED has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://fred.stlouisfed.org/docs/api/api_key.html; this and fred_series_observations are the key-required macro tools — the other 112 tools stay keyless). Input: `query` (the search_text, required, e.g. 'unemployment rate' / 'CPI' / '10-year treasury'), optional `limit` (default 25, max 1000), `offset`. Returns { series:[{ id, title, frequency, frequencyShort, units, seasonalAdjustment, observationStart, observationEnd, lastUpdated, popularity }] } + honest _meta. Feed `id` into fred_series_observations for the time series. HONESTY: totalAvailable is FRED's EXACT reported `count` (offset pagination via hasMore/nextOffset — never fabricated); every scalar is null-never-empty-string; a genuine no-match ⇒ honest empty (returned:0); a 400 (bad/missing key) ⇒ invalid_input CARRYING FRED's error_message; a 5xx ⇒ THROWS; a 200 non-JSON / non-array `seriess` ⇒ schema_drift. The key rides ONLY in the &api_key= query param — never logged or echoed.",
+      "Discover FRED economic series (GDP, CPI, interest rates, unemployment, PPI…) by free-text search (FRED /fred/series/search; api.stlouisfed.org). ★REQUIRES a free FRED_API_KEY: FRED has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://fred.stlouisfed.org/docs/api/api_key.html; fred_series_observations shares this key — call api_key_status to see every source's key requirement). Input: `query` (the search_text, required, e.g. 'unemployment rate' / 'CPI' / '10-year treasury'), optional `limit` (default 25, max 1000), `offset`. Returns { series:[{ id, title, frequency, frequencyShort, units, seasonalAdjustment, observationStart, observationEnd, lastUpdated, popularity }] } + honest _meta. Feed `id` into fred_series_observations for the time series. HONESTY: totalAvailable is FRED's EXACT reported `count` (offset pagination via hasMore/nextOffset — never fabricated); every scalar is null-never-empty-string; a genuine no-match ⇒ honest empty (returned:0); a 400 (bad/missing key) ⇒ invalid_input CARRYING FRED's error_message; a 5xx ⇒ THROWS; a 200 non-JSON / non-array `seriess` ⇒ schema_drift. The key rides ONLY in the &api_key= query param — never logged or echoed.",
     inputSchema: FredSearchSeriesInput,
     handler: (input) => fred.searchSeries(input),
   }),
@@ -5023,6 +5862,84 @@ export const TOOLS: ToolDef[] = [
     inputSchema: FredSeriesObservationsInput,
     handler: (input) => fred.seriesObservations(input),
   }),
+  // ━━━ openFDA recall/enforcement (api.fda.gov) — product-safety recalls (1) ━━━ ADR-0054
+  // KEYLESS with an OPTIONAL OPENFDA_API_KEY (raises the rate limit; keyless works
+  // ~1000/day — it NEVER throws for a missing key, unlike the key-REQUIRED sources).
+  // Structured filters ONLY (no raw Lucene passthrough — the tool assembles + escapes
+  // the search= string, injection-safe). ★P1: totalAvailable = meta.results.total
+  // (EXACT). ★P2 crux: a no-match query returns openFDA HTTP 404 NOT_FOUND ⇒ an honest
+  // empty, never a throw. The optional key rides &api_key= ONLY.
+  defineTool({
+    name: "openfda_enforcement",
+    description:
+      "Search openFDA recall/enforcement records — drug/device/food product recalls with the recalling firm, product, reason, FDA classification (Class I/II/III), status, and geography (openFDA /{category}/enforcement.json; api.fda.gov). KEYLESS (an OPTIONAL free OPENFDA_API_KEY only RAISES the rate limit — keyless works at ~1000 requests/day; it NEVER throws for a missing key; get one at https://open.fda.gov/apis/authentication/; call api_key_status to see every source's key requirement). Input: `category` (drug|device|food, default drug), and STRUCTURED filters — `firm` (→recalling_firm), `product` (→product_description), `reason` (→reason_for_recall), `classification` (Class I|II|III), `status` (e.g. Ongoing/Terminated/Completed), `state` (2-letter, e.g. 'CA') — the tool safely assembles + escapes these into the openFDA search= Lucene string (NO raw passthrough — injection-safe), plus `limit` (1..100, default 25) and `skip` (offset ≥0). Returns { recalls:[{ recallingFirm, productDescription, reasonForRecall, classification, status, state, city, recallInitiationDate, recallNumber, voluntaryMandated, distributionPattern }] } + honest _meta. HONESTY: totalAvailable is openFDA's EXACT meta.results.total (skip/limit pagination via hasMore/nextOffset — never results.length); every scalar (dates included, recall_initiation_date is a YYYYMMDD string) is null-never-empty-string. ★A no-match query returns openFDA HTTP 404 NOT_FOUND ⇒ an HONEST EMPTY (returned:0, totalAvailable:0), NOT an error; a 400 syntax error ⇒ invalid_input surfacing openFDA's message; a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The optional key rides ONLY the &api_key= query param — never logged or echoed.",
+    inputSchema: OpenfdaEnforcementInput,
+    handler: (input) => openfda.enforcement(input),
+  }),
+  // ━━━ openFDA 510(k) device clearances (api.fda.gov) — medical-device regulatory (1) ━━━ ADR-0056
+  // KEYLESS with an OPTIONAL OPENFDA_API_KEY (raises the rate limit; keyless works
+  // ~1000/day — never throws for a missing key). SAME source/envelope/crux as
+  // openfda_enforcement (reuses openfda.ts's fetchOpenfda/readOpenfdaError/luceneQuote).
+  // Structured filters ONLY (no raw Lucene passthrough — the tool assembles + escapes the
+  // search= string, injection-safe). ★P1: totalAvailable = meta.results.total (EXACT,
+  // ~175507). ★P2 crux: a no-match query returns openFDA HTTP 404 NOT_FOUND ⇒ an honest
+  // empty, never a throw. The optional key rides &api_key= ONLY.
+  defineTool({
+    name: "openfda_device_clearances",
+    description:
+      "Search openFDA 510(k) DEVICE CLEARANCES — the FDA's premarket-notification (510(k)) clearances for medical devices, with the applicant/manufacturer, device name, clearance number (K-number), decision (date + description), clearance type, product code, advisory committee, and geography (openFDA /device/510k.json; api.fda.gov). KEYLESS (an OPTIONAL free OPENFDA_API_KEY only RAISES the rate limit — keyless works at ~1000 requests/day; it NEVER throws for a missing key; get one at https://open.fda.gov/apis/authentication/; call api_key_status to see every source's key requirement). Input: STRUCTURED filters — `applicant` (→applicant), `deviceName` (→device_name), `productCode` (→product_code), `clearanceType` (→clearance_type, e.g. Traditional/Special/Abbreviated), `kNumber` (→k_number, e.g. 'K123456'), `state` (2-letter, e.g. 'CA') — the tool safely assembles + escapes these into the openFDA search= Lucene string (NO raw passthrough — injection-safe), plus `limit` (1..100, default 25) and `skip` (offset ≥0). Returns { clearances:[{ applicant, deviceName, kNumber, decisionDate, decisionDescription, clearanceType, productCode, advisoryCommittee, state }] } + honest _meta. HONESTY: totalAvailable is openFDA's EXACT meta.results.total (skip/limit pagination via hasMore/nextOffset — never results.length); every scalar (dates included, decision_date is a YYYY-MM-DD string) is null-never-empty-string. ★A no-match query returns openFDA HTTP 404 NOT_FOUND ⇒ an HONEST EMPTY (returned:0, totalAvailable:0), NOT an error; a 400 syntax error ⇒ invalid_input surfacing openFDA's message; a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The optional key rides ONLY the &api_key= query param — never logged or echoed.",
+    inputSchema: OpenfdaDeviceClearancesInput,
+    handler: (input) => openfdaDevice.deviceClearances(input),
+  }),
+  // ━━━ NHTSA vehicle safety (api.nhtsa.gov) — vehicle/parts supplier vetting (2) ━━━ ADR-0057
+  // ★KEYLESS — no API key at all (no parameter, no header). The cross-agency
+  // product-safety family alongside openFDA (medical). Both tools share
+  // make/model/modelYear inputs and return the COMPLETE matching set (no pagination
+  // ⇒ totalAvailable = the upstream Count/count, complete:true). ★The complaints VIN
+  // (an individual-vehicle PII identifier) is EXCLUDED from the output.
+  defineTool({
+    name: "nhtsa_recalls",
+    description:
+      "Look up NHTSA vehicle safety RECALLS for a specific vehicle — the manufacturer's recall campaigns with the affected component, the safety consequence, the remedy, and 'do not drive'/'park outside'/over-the-air-update flags (NHTSA /recalls/recallsByVehicle; api.nhtsa.gov). KEYLESS — no API key is required or accepted. Input: `make` (required, e.g. 'honda'), `model` (required, e.g. 'accord'), `modelYear` (required, 4-digit, e.g. '2020'). Returns { recalls:[{ campaignNumber, manufacturer, component, summary, consequence, remedy, reportReceivedDate, parkIt, parkOutside, overTheAirUpdate }] } + honest _meta. HONESTY: totalAvailable is NHTSA's EXACT Count and NHTSA returns the COMPLETE set for the vehicle (no pagination) ⇒ complete:true; a no-match (Count 0 / a bad make/model) ⇒ an HONEST EMPTY (returned:0), NOT an error; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The park-it/park-outside/over-the-air-update flags are preserved as booleans (never a fabricated false); dates are strings; every scalar is null-never-empty-string. Fixed host api.nhtsa.gov (SSRF-guarded); make/model are letters/digits/space/hyphen only and modelYear is ^\\d{4}$.",
+    inputSchema: NhtsaVehicleInput,
+    handler: (input) => nhtsa.recalls(input),
+  }),
+  defineTool({
+    name: "nhtsa_complaints",
+    description:
+      "Look up NHTSA consumer COMPLAINTS for a specific vehicle — owner-filed safety complaints with the affected component, crash/fire flags, injury/death counts, and incident/filing dates (NHTSA /complaints/complaintsByVehicle; api.nhtsa.gov). KEYLESS — no API key is required or accepted. Input: `make` (required, e.g. 'honda'), `model` (required, e.g. 'accord'), `modelYear` (required, 4-digit, e.g. '2020'). Returns { complaints:[{ odiNumber, manufacturer, component, summary, crash, fire, numberOfInjuries, numberOfDeaths, dateOfIncident, dateComplaintFiled }] } + honest _meta. ★PRIVACY: the NHTSA complaint VIN (an individual-vehicle identifier) is INTENTIONALLY EXCLUDED from the output — the B2G signal is the manufacturer/component/crash/fire/injury/death safety history, not the VIN. HONESTY: totalAvailable is NHTSA's EXACT count and NHTSA returns the COMPLETE set for the vehicle (no pagination) ⇒ complete:true; a no-match ⇒ an HONEST EMPTY (returned:0), NOT an error; crash/fire preserved as booleans (never a fabricated false); numberOfInjuries/numberOfDeaths via numeric coercion (a genuine 0 stays 0, NEVER null-for-0); dates are strings; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. Fixed host api.nhtsa.gov (SSRF-guarded); make/model are letters/digits/space/hyphen only and modelYear is ^\\d{4}$.",
+    inputSchema: NhtsaVehicleInput,
+    handler: (input) => nhtsa.complaints(input),
+  }),
+  // ━━━ CPSC consumer-product recalls (www.saferproducts.gov) — goods/import vetting (1) ━━━ ADR-0058
+  // ★KEYLESS — no API key at all (no parameter, no header). The third leg of the
+  // cross-agency product-safety family alongside NHTSA (vehicles) and openFDA
+  // (medical). The response is a bare JSON ARRAY with NO total-count field and NO
+  // pagination ⇒ totalAvailable = the returned count, complete:true. All filters are
+  // optional; with NO filter the tool bounds results to a ~90-day default window
+  // (disclosed) rather than silently fetch the entire dataset.
+  defineTool({
+    name: "cpsc_recalls",
+    description:
+      "Look up U.S. CPSC consumer-product RECALLS — the recall title, hazard description, remedy, affected products, manufacturers, retailers, injuries, and country of manufacture (CPSC SaferProducts /RestWebServices/Recall; www.saferproducts.gov). The consumer-goods / import product-safety lane alongside nhtsa_recalls (vehicles) and openfda (medical). KEYLESS — no API key is required or accepted. Inputs (ALL optional): `dateStart`/`dateEnd` (YYYY-MM-DD recall date range), `productName` (substring), `manufacturer` (substring), `recallNumber` (a specific CPSC recall number). Returns { recalls:[{ recallNumber, recallDate, title, description, url, products:[names], numberOfUnits, manufacturers:[names], retailers:[names], hazards:[descriptions], remedies:[descriptions], injuries:[names], manufacturerCountries:[names] }] } + honest _meta. HONESTY: the CPSC response is a bare array with NO count field and NO pagination — it returns the COMPLETE matching set, so totalAvailable = the number of returned recalls and complete:true (never a fabricated total). ★With NO filter given, results are bounded to a DEFAULT ~90-day recent window (RecallDateStart, disclosed in _meta.notes) rather than a silent whole-dataset fetch. An empty result ⇒ an HONEST EMPTY (returned:0), NOT an error; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROWS; a 200 non-JSON OR a non-array body ⇒ schema_drift. Nested arrays are flattened to name/description strings (an empty {} object is skipped, never fabricated); NumberOfUnits is free text kept as a string; dates are strings; every scalar is null-never-empty-string. Fixed host www.saferproducts.gov (SSRF-guarded); dates are ^\\d{4}-\\d{2}-\\d{2}$ and recallNumber is letters/digits/hyphen only.",
+    inputSchema: CpscRecallsInput,
+    handler: (input) => cpsc.recalls(input),
+  }),
+  // ━━━ BEA Regional Economic Accounts (apps.bea.gov) — regional GDP/income (1) ━━━ ADR-0051
+  // ★The server's THIRD KEY-REQUIRED source: the BEA Data API has NO keyless tier, so
+  // WITHOUT a BEA_API_KEY this tool throws an honest invalid_input config error (the
+  // most other tools stay keyless — see api_key_status). County/state/MSA GDP-by-industry + personal income —
+  // the regional place-of-performance lane. ★The P2 crux: a missing/invalid key returns
+  // HTTP 200 carrying BEAAPI.Results.Error (NOT an HTTP error status), which is detected
+  // BEFORE the Data-array drift check and surfaced as invalid_input (never a fake empty).
+  // DataValue is a comma-formatted string; suppression codes ((NA)/(D)/(NM)/(L)/*) → null.
+  defineTool({
+    name: "bea_regional_data",
+    description:
+      "Regional (county / state / MSA) economic data — GDP by industry and personal income — from the US Bureau of Economic Analysis (BEA) Regional Economic Accounts (apps.bea.gov/api/data, dataset 'Regional'). ★REQUIRES a free BEA_API_KEY: the BEA Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://apps.bea.gov/API/signup/; call api_key_status to see every source's key requirement). Input: `tableName` (required, e.g. 'CAGDP2' county GDP by industry, 'SAGDP2N' state GDP, 'CAINC1'/'SAINC1' personal income), `geoFips` (required — 'STATE' for all states, a county FIPS like '06075', or an MSA code), `lineCode` (required — an integer industry line like '1', or 'ALL'), optional `year` ('LAST5' default, a 4-digit year, or 'ALL'), `frequency` ('A' annual default, or 'Q'). Returns { rows:[{ geoFips, geoName, timePeriod, lineCode, dataValue, unitOfMeasure, unitMult, noteRef }], notes:[{ noteRef, noteText }] } + honest _meta. ★HONESTY (the crux): a missing/invalid key — or ANY bad parameter — returns HTTP 200 carrying an Error object (NOT an HTTP error status); this is detected and surfaced as invalid_input carrying BEA's APIErrorDescription — NEVER a fake empty. dataValue is parsed from BEA's comma-formatted string ('1,234,567'→1234567); BEA suppression/not-available codes ((NA)/(D)/(NM)/(L)/*) map to null — NEVER 0 (a genuine 0 stays 0). unitMult (a power-of-10 multiplier) and unitOfMeasure are reported ALONGSIDE the raw dataValue — the value is NOT multiplied in (apply unitMult yourself). BEA returns the COMPLETE set for the filter (no pagination) ⇒ totalAvailable = the row count, complete:true; a genuine empty Data:[] ⇒ honest empty (returned:0); a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The key rides ONLY in the UserID= query param — never logged or echoed.",
+    inputSchema: BeaRegionalDataInput,
+    handler: (input) => bea.regionalData(input),
+  }),
   // ━━━ GSA Federal Travel Per-Diem (api.gsa.gov) — travel-cost lane (1) ━━━ ADR-0050
   // The lodging + M&IE reimbursement ceilings the federal government pays for official
   // travel, by city/state OR zip for a year. SAME host (api.gsa.gov) + SAME api.data.gov
@@ -5037,15 +5954,87 @@ export const TOOLS: ToolDef[] = [
     inputSchema: GsaPerdiemRatesInput,
     handler: (input) => gsaPerdiem.perdiemRates(input),
   }),
+  // ━━━ US DOL Data API v4 (apiprod.dol.gov) — the labor-enforcement lane (2) ━━━ ADR-0053
+  // A DELIBERATE key split: dol_list_datasets (the dataset CATALOG) is KEYLESS;
+  // dol_get_dataset (the DATA endpoint) is the server's 4th REQUIRED key (DOL_API_KEY —
+  // the data endpoint has NO keyless tier, so without the key it THROWS pre-fetch). The
+  // key rides the X-API-KEY HEADER ONLY. The data-record envelope is key-gated/unverified
+  // ⇒ records are surfaced VERBATIM + totalAvailable defaults null (never `returned` faked
+  // as the total). agency/query filtering on the catalog is CLIENT-SIDE.
+  defineTool({
+    name: "dol_list_datasets",
+    description:
+      "List the US Department of Labor Data API v4 dataset catalog (apiprod.dol.gov /v4/datasets) — the machine inventory of DOL enforcement/statistics datasets (WHD wage & hour, OSHA inspections, ILAB child/forced-labor reports, MSHA mine safety, ETA …). KEYLESS: the catalog needs NO API key (only dol_get_dataset does). Input (all optional): `agency` (CLIENT-SIDE filter by agency abbreviation like 'WHD'/'OSHA'/'ILAB', or an agency-name substring), `query` (CLIENT-SIDE free-text substring over dataset name/description/category/table/endpoint), `limit` (default 25, max 200), `offset`. Returns { datasets:[{ name, tablename, apiUrl, agency, agencyAbbr, description, frequency, datasetType, category }] } + honest _meta. ★Feed a row's `apiUrl` (the DOL 'api_url' endpoint) + its `agencyAbbr` into dol_get_dataset to fetch that dataset's records. HONESTY: agency/query filtering is CLIENT-SIDE (the DOL catalog API does not filter server-side, verified live); totalAvailable is the catalog's REAL total (meta.total_count) for an unfiltered scan, or the exact filtered-set size (the whole catalog is fetched in one page); offset pagination. Every scalar is null-never-empty-string. A non-array `datasets` / 200 non-JSON ⇒ schema_drift; a 5xx ⇒ THROWS.",
+    inputSchema: DolListDatasetsInput,
+    handler: (input) => dol.listDatasets(input),
+  }),
+  defineTool({
+    name: "dol_get_dataset",
+    description:
+      "Fetch records from ONE US DOL dataset (apiprod.dol.gov /v4/get/{agency}/{endpoint}/json). ★REQUIRES a free DOL_API_KEY: the DOL DATA endpoint has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://dataportal.dol.gov/registration; the dataset CATALOG — dol_list_datasets — and agency list stay keyless). Input: `agency` (required — the `agencyAbbr` from dol_list_datasets, e.g. 'WHD', 'OSHA', 'ILAB'; rides the PATH, ^[A-Za-z0-9_]+$), `table` (required — the dataset's `apiUrl` endpoint from dol_list_datasets, e.g. 'Child_Labor_Report__2016_to_2022'; rides the PATH, ^[A-Za-z0-9_]+$), optional `limit` (default 10, max 100), `offset`, `filterField`+`filterValue` (a paired equality filter → a DOL filter_object), `fields` (best-effort column selection). Returns { records:[…verbatim dataset rows…] } + honest _meta. HONESTY: records are surfaced VERBATIM (the data-record envelope is key-gated and unverified, so field names/values are preserved as-is — a genuine 0 stays 0, a missing field stays null; the tool never coerces or fabricates). totalAvailable is a real count field ONLY when the response carries one, else null (an honest unknown — `returned` is NEVER passed off as the total); offset pagination (a full page ⇒ hasMore, page forward to confirm). A missing/invalid key (401/403) ⇒ invalid_input carrying the DOL_API_KEY guidance (never empty); a 400 ⇒ invalid_input; a genuine empty ⇒ honest empty (returned:0); a 429 ⇒ rate_limited THROWS (Retry-After honored); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / no row array ⇒ schema_drift. The key rides ONLY in the X-API-KEY request header — never the URL / _meta / a log.",
+    inputSchema: DolGetDatasetInput,
+    handler: (input) => dol.getDataset(input),
+  }),
+  // ━━━ US Senate LDA lobbying filings (lda.senate.gov) — the lobbying/B2G lane (1) ━━━ ADR-0052
+  // Who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue — the
+  // registrant→client→government-entity signal no contract/spending source carries.
+  // KEYLESS (anonymous 200); the OPTIONAL free LDA_API_KEY only raises the rate limit
+  // and rides the Authorization: Token … header ONLY (the socrata app-token lineage —
+  // NOT key-required). ★count is the API's REAL total (~1.95M) — never results.length;
+  // page-based pagination. income/expenses are null-or-decimal-string ⇒ null-never-0.
+  defineTool({
+    name: "lda_search_filings",
+    description:
+      "Search US Senate LDA (Lobbying Disclosure Act) filings — who is paid HOW MUCH to lobby WHICH federal agency on WHICH issue (lda.senate.gov/api/v1/filings, KEYLESS — anonymous access works; an optional free LDA_API_KEY only raises the rate limit). All inputs optional: `registrantName` (the lobbying firm/in-house filer), `clientName` (who it's for), `lobbyistName`, `filingYear` (4-digit), `filingType` (short code, e.g. 'Q1'/'RR'/'YE'), `agency` (the federal government_entity lobbied — the B2G signal), `issue` (specific lobbying issues text), `page` (1-based, default 1), `pageSize` (1..25, default 25). Returns { filings:[{ filingUuid, filingType, filingYear, filingPeriod, incomeUsd, expensesUsd, registrant, client, lobbyingActivities:[{ issueCode, description, governmentEntities:[names] }], documentUrl, postedDate, terminationDate }] } + honest _meta. HONESTY: totalAvailable is the API's REAL total match count (the corpus is ~1.95M filings) — NOT the rows on this page; pagination is page-based (pass the next page number when hasMore). incomeUsd/expensesUsd are parsed from the null-or-decimal-string income/expenses — null (not reported) ⇒ null, NEVER 0 (a genuine 0 stays 0); a filing reports EITHER income OR expenses, so the other is typically null. Missing lobbying_activities/government_entities ⇒ empty arrays (never fabricated). A genuine no-match (results:[]) ⇒ honest empty (returned:0); a 400 (bad filter) ⇒ invalid_input surfacing the API's message; a 429 ⇒ rate_limited THROWS (Retry-After honored, never routed around); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / non-array results / non-number count ⇒ schema_drift. The optional key rides ONLY in the Authorization: Token header (never the URL/_meta).",
+    inputSchema: LdaSearchFilingsInput,
+    handler: (input) => lda.searchFilings(input),
+  }),
+  // ━━━ US federal court opinions (www.courtlistener.com) — the litigation lane (1) ━━━ ADR-0055
+  // Federal court decisions — the judicial signal no contract/spending/lobbying source
+  // carries (uscfc bid-protest/contract-claim opinions, cafc contract/patent appeals).
+  // ★PROVENANCE: CourtListener (Free Law Project, a non-profit), NOT a .gov API — PACER
+  // (the .gov source) is paywalled. KEYLESS (anonymous 200); the OPTIONAL free
+  // COURTLISTENER_API_TOKEN only raises the rate limit, riding the Authorization: Token …
+  // header ONLY. ★count is the API's REAL total — never results.length; CURSOR pagination
+  // (nextCursor extracted from `next`, host re-asserted). type=o FIXED.
+  defineTool({
+    name: "courtlistener_search_opinions",
+    description:
+      "Search US FEDERAL COURT OPINIONS (case law / litigation) via CourtListener (www.courtlistener.com/api/rest/v4/search, type=o). ★PROVENANCE: the DATA is US federal court PUBLIC RECORDS, but the API is CourtListener, run by the Free Law Project (a NON-PROFIT) — this is NOT a .gov API; CourtListener republishes these records KEYLESS because the .gov primary source (PACER) is PAYWALLED. KEYLESS (anonymous access works; an optional free COURTLISTENER_API_TOKEN only raises the rate limit; get one at https://www.courtlistener.com/help/api/rest/; call api_key_status to see every source's key requirement). All inputs optional: `query` (full-text → q), `court` (a court id, ^[a-z0-9]+$ — e.g. 'uscfc' US Court of Federal Claims for contract claims/bid protests, 'cafc' Federal Circuit for contract/patent appeals, 'scotus'), `dateFiledAfter`/`dateFiledBefore` (ISO ^\\d{4}-\\d{2}-\\d{2}$ → filed_after/filed_before), `natureOfSuit` (folded into the q query — no verified dedicated filter, disclosed in notes), `cursor` (opaque continuation — pass back _meta.nextCursor), `order` (→ order_by, default 'dateFiled desc'). Returns { opinions:[{ caseName, court, courtId, dateFiled, docketNumber, natureOfSuit, status, judge, citation, absoluteUrl }] } + honest _meta. HONESTY: totalAvailable is the API's REAL `count` (the total match count for the filter) — NOT the rows on this page; pagination is an OPAQUE CURSOR (offset/nextOffset are null/meaningless — pass _meta.nextCursor back as `cursor`; nextCursor:null/hasMore:false = last page). CourtListener v4 stops counting on deep cursor pages (count:null) ⇒ totalAvailable:null is DISCLOSED, never faked as results.length. dateFiled is a date STRING; citation may be an array/object ⇒ flattened to a safe string/string[] (never fabricated); judge/natureOfSuit/docketNumber are null when absent (never ''); absoluteUrl is the full https://www.courtlistener.com link. A genuine no-match (results:[]) ⇒ honest empty (returned:0); a 400 (bad param) ⇒ invalid_input surfacing the API's message; a 429 (unauth throttle) ⇒ rate_limited THROWS (Retry-After honored, never routed around); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / non-array results / a count that is neither a number nor null ⇒ schema_drift; an off-host `next` is REFUSED (SSRF). The optional token rides ONLY in the Authorization: Token header (never the URL/_meta).",
+    inputSchema: CourtlistenerSearchOpinionsInput,
+    handler: (input) => courtlistener.searchOpinions(input),
+  }),
+  // ━━━ US tax-exempt nonprofits (projects.propublica.org) — the nonprofit lane (2) ━━━ ADR-0060
+  // Who a 501(c) org IS (EIN, NTEE, subsection, ruling date, status) + its Form 990
+  // FINANCIALS (revenue/expenses/assets/liabilities by year) — the nonprofit/grantee/
+  // subcontractor vetting signal no contract/spending/grant/lobbying source carries.
+  // ★PROVENANCE: IRS Form 990 public records republished KEYLESS by ProPublica Nonprofit
+  // Explorer (a non-profit newsroom), NOT a .gov API (the IRS has no clean query API).
+  // KEYLESS (no key). search total_results is the REAL total — never organizations.length;
+  // financials totalAvailable = filings.length (the complete set). Money via num (null-never-0).
+  defineTool({
+    name: "nonprofit_search",
+    description:
+      "Search US TAX-EXEMPT NONPROFITS (501(c) organizations) by IRS Form 990 data via ProPublica Nonprofit Explorer (projects.propublica.org/nonprofits/api/v2/search). ★PROVENANCE: the DATA is IRS Form 990 filings — FEDERAL tax-exempt PUBLIC RECORDS — but the API is ProPublica Nonprofit Explorer, run by ProPublica (a NON-PROFIT newsroom) — this is NOT a .gov API; ProPublica republishes these records KEYLESS because the IRS itself has no clean query API (only bulk downloads / a web UI). KEYLESS (no key of any kind). All inputs optional: `query` (full-text org name/keyword → q), `state` (2-letter code → state[id], ^[A-Za-z]{2}$), `ntee` (NTEE major category, integer 1..10 → ntee[id]), `page` (0-BASED, default 0). Returns { organizations:[{ ein, name, city, state, nteeCode, subsectionCode }] } + honest _meta. HONESTY: totalAvailable is the API's REAL total_results (the total match count for the query) — NOT the organizations on this page; pagination is page-based and 0-INDEXED (pass page=cur_page+1 when hasMore). ein/nteeCode/subsectionCode are strings (never num-coerced). A genuine no-match (organizations:[]) ⇒ honest empty (returned:0, complete:true); a 4xx ⇒ invalid_input; a 429 ⇒ rate_limited THROWS (Retry-After honored, never routed around); a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / non-array organizations / non-number total_results ⇒ schema_drift. Data is IRS Form 990 data via ProPublica Nonprofit Explorer, disclosed in _meta.source and a note.",
+    inputSchema: NonprofitSearchInput,
+    handler: (input) => nonprofit.search(input),
+  }),
+  defineTool({
+    name: "nonprofit_financials",
+    description:
+      "Fetch ONE US tax-exempt nonprofit's IRS Form 990 profile + FINANCIALS by EIN via ProPublica Nonprofit Explorer (projects.propublica.org/nonprofits/api/v2/organizations/{ein}.json). ★PROVENANCE: the DATA is IRS Form 990 filings (federal tax-exempt public records) but the API is ProPublica Nonprofit Explorer, run by ProPublica (a NON-PROFIT newsroom) — NOT a .gov API; ProPublica republishes these records KEYLESS because the IRS has no clean query API. KEYLESS (no key). Input: `ein` (required — the Employer Identification Number, 1..9 digits ^\\d{1,9}$, e.g. '530196605' American National Red Cross; rides the URL path). Returns { organization:{ ein, name, address, city, state, zip, nteeCode, subsectionCode, rulingDate, statusCode }, filings:[{ taxYear, formType, revenueUsd, expensesUsd, assetsUsd, liabilitiesUsd, pdfUrl }] } + honest _meta. HONESTY: the four Form 990 figures (revenueUsd/expensesUsd/assetsUsd/liabilitiesUsd, from totrevenue/totfuncexpns/totassetsend/totliabend) ride null-never-0 coercion — a genuine reported 0 stays 0, an absent figure ⇒ null (NEVER 0-faked); ein/codes are strings; rulingDate is a date string. totalAvailable = filings.length (the COMPLETE Form 990 filing set from the one detail document — no pagination). An unknown EIN (HTTP 404) ⇒ not_found (NEVER a fabricated empty org); a 4xx ⇒ invalid_input; a 429 ⇒ rate_limited THROWS; a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON / non-object organization / non-array filings_with_data ⇒ schema_drift. Data is IRS Form 990 data via ProPublica Nonprofit Explorer, disclosed in _meta.source and a note.",
+    inputSchema: NonprofitFinancialsInput,
+    handler: (input) => nonprofit.financials(input),
+  }),
   // ━━━ Self-service key discovery (1) ━━━
   // KEYLESS. A local status query — reads process.env (+ any .env auto-loaded at
   // startup) and reports, per key, whether it is set (a BOOLEAN — the key VALUE is
-  // NEVER read into the output). Makes the 2-required + 5-optional key situation
+  // NEVER read into the output). Makes the 4-required + 6-optional key situation
   // discoverable without reading source or docs.
   defineTool({
     name: "api_key_status",
     description:
-      "List every API key this server can use, whether each is REQUIRED or OPTIONAL, the free signup URL + what it unlocks, and whether it is CURRENTLY configured — a boolean only; the key VALUE is NEVER shown. KEYLESS (no input). Most sources are keyless; only Census (census_business_patterns) and FRED (2 tools) REQUIRE a key (they throw without one), the other 5 keys are OPTIONAL (raise a rate limit or unlock one filter). Keys can be set as host env vars OR in a `.env` file in the server's working directory (auto-loaded at startup; real env wins over .env). Returns { keys:[{ envVar, sources[], required, signupUrl, unlocks, note, currentlySet }], requiredMissing:[envVars], optionalMissing:[envVars], allKeysFree:true }. This tool tells you the CONFIG state; to verify a key actually WORKS, call that source's own tool. Getting a key (creating the account at the signup URL) is your step — the server automates discovery + configuration, not signup.",
+      "List every API key this server can use, whether each is REQUIRED or OPTIONAL, the free signup URL + what it unlocks, and whether it is CURRENTLY configured — a boolean only; the key VALUE is NEVER shown. KEYLESS (no input). Most sources are keyless; four sources need a key — Census (census_business_patterns), FRED (2 tools), and BEA (bea_regional_data) require one outright, and DOL's DATA endpoint (dol_get_dataset) needs one too (its catalog, dol_list_datasets, stays keyless) — the other 6 keys are OPTIONAL (raise a rate limit or unlock one filter). Keys can be set as host env vars OR in a `.env` file in the server's working directory (auto-loaded at startup; real env wins over .env). Returns { keys:[{ envVar, sources[], required, signupUrl, unlocks, note, currentlySet }], requiredMissing:[envVars], optionalMissing:[envVars], allKeysFree:true }. This tool tells you the CONFIG state; to verify a key actually WORKS, call that source's own tool. Getting a key (creating the account at the signup URL) is your step — the server automates discovery + configuration, not signup.",
     inputSchema: ApiKeyStatusInput,
     handler: async () => keys.apiKeyStatus(),
   }),