@cliwant/mcp-sam-gov 1.3.0 → 1.4.0

package/dist/server.js

@@ -45,11 +45,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";
@@ -59,6 +66,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";
@@ -68,7 +79,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.3.0";
+const SERVER_VERSION = "1.4.0";
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 const SamSearchInput = z.object({
     query: z.string().optional().describe("Free-text title query"),
@@ -2824,6 +2835,248 @@ const CensusBusinessPatternsInput = z.object({
         .optional()
         .describe("OPTIONAL client-side top-N cap on the returned rows. CBP has NO server-side pagination, so this slices AFTER the full set is fetched and DISCLOSES the omission (totalAvailable stays the full count). Omit to return every matching row."),
 });
+// ─── 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
@@ -2880,6 +3133,160 @@ const FredSeriesObservationsInput = z.object({
         .optional()
         .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
@@ -3066,6 +3473,92 @@ const LdaSearchFilingsInput = z.object({
         .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({});
 // Build a ToolDef whose `handler` is type-checked against the schema's inferred
@@ -4331,16 +4824,90 @@ export const TOOLS = [
     // ━━━ 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.",
+        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; 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
@@ -4348,7 +4915,7 @@ export const TOOLS = [
     // bid escalation / market timing. A missing observation ('.') maps to null (never 0).
     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.",
+        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; 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),
     }),
@@ -4358,17 +4925,75 @@ export const TOOLS = [
         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
-    // other 116 tools stay keyless). County/state/MSA GDP-by-industry + personal income —
+    // 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/; Census, FRED, and BEA are the only key-required sources — every other tool is keyless). 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.",
+        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),
     }),
@@ -4400,7 +5025,7 @@ export const TOOLS = [
     }),
     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://dol.gov/developer; 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.",
+        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),
     }),
@@ -4417,6 +5042,40 @@ export const TOOLS = [
         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