@cliwant/mcp-sam-gov 1.10.0 → 1.12.0

package/src/sam-gov/client.ts

@@ -353,11 +353,20 @@ export class SamGovClient {
     filters: SamSearchFilters,
   ): Promise<SamSearchResult> {
     const url = new URL(`${PUBLIC_BASE}/sgs/v1/search/`);
+    // Keyless HAL pagination is by PAGE (page × size), not a row offset — the
+    // list endpoint pages correctly (VERIFIED LIVE 2026-07: page=0 and page=1
+    // return disjoint result sets for the same query). Map the caller's row
+    // `offset` onto the page grid; a non-page-aligned offset snaps DOWN to its
+    // page boundary and we return the SERVED offset (page × size) so `_meta`
+    // never claims an offset the upstream didn't honor. (The authenticated path,
+    // buildAuthSearchUrl, honors an arbitrary `offset` directly.)
+    const size = filters.limit ?? 25;
+    const page = Math.max(0, Math.floor((filters.offset ?? 0) / size));
     url.searchParams.set("index", "opp");
-    url.searchParams.set("page", "0");
+    url.searchParams.set("page", String(page));
     url.searchParams.set("mode", "search");
     url.searchParams.set("sort", "-modifiedDate");
-    url.searchParams.set("size", String(filters.limit ?? 25));
+    url.searchParams.set("size", String(size));
     url.searchParams.set("is_active", "true");
     // Keyless HAL facet params — VERIFIED LIVE (2026-07). The list endpoint
     // honors these server-side: result counts drop correctly AND every returned
@@ -457,8 +466,8 @@ export class SamGovClient {
     });
     return {
       totalRecords,
-      limit: filters.limit ?? 25,
-      offset: filters.offset ?? 0,
+      limit: size,
+      offset: page * size, // the SERVED offset (page-aligned), never the raw request
       opportunitiesData: data,
     };
   }

package/src/server.ts

@@ -106,7 +106,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.10.0";
+const SERVER_VERSION = "1.12.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -3759,7 +3759,7 @@ const CensusBusinessPatternsInput = z.object({
     .regex(/^\d{4}$/)
     .optional()
     .describe(
-      "The CBP data year (default '2022', the latest confirmed vintage). Validated ^\\d{4}$ (it rides in the request path).",
+      "The CBP data year (default '2023', the latest published vintage — CBP is released with a ~2-year lag). Validated ^\\d{4}$ (it rides in the request path).",
     ),
   limit: z
     .number()
@@ -4418,7 +4418,7 @@ const GsaPerdiemRatesInput = z
       .regex(/^\d{4}$/)
       .optional()
       .describe(
-        "The per-diem fiscal year (default '2025'). Validated ^\\d{4}$ (it rides in the request path).",
+        "The per-diem fiscal year (default: the current U.S. federal fiscal year, computed at call time — GSA sets rates per FY, Oct 1–Sep 30). Validated ^\\d{4}$ (it rides in the request path).",
       ),
   })
   .describe(
@@ -4543,7 +4543,7 @@ const LdaSearchFilingsInput = z.object({
     .string()
     .min(1)
     .optional()
-    .describe("Filter by the federal government entity lobbied (maps to government_entity — the B2G signal), e.g. 'DEPARTMENT OF DEFENSE'."),
+    .describe("NOTE: the keyless /filings/ endpoint has NO server-side government-entity filter — the LDA API silently ignores it, so this value is NOT applied (reported in _meta.filtersDropped, never as a narrowed total). Government entities are nested per lobbying activity (each filing's lobbyingActivities[].governmentEntities); to find who lobbied an agency, narrow by registrantName/clientName/issue and inspect those nested entities. Retained for discoverability of the limitation."),
   issue: z
     .string()
     .min(1)
@@ -4895,6 +4895,21 @@ export const TOOLS: ToolDef[] = [
             "The organization-name filter is NOT supported by the keyless endpoint and was ignored (results are unfiltered on organization). Set SAM_GOV_API_KEY to filter by organization, or filter client-side on the returned `agency` field.",
           );
         }
+        // Pagination honesty: the keyless HAL endpoint pages by PAGE (page × size),
+        // not an arbitrary row offset, so a requested offset that is not a multiple
+        // of `limit` snaps DOWN to its page boundary. Disclose the snap so the AI
+        // never believes it read rows [offset..offset+limit) when it actually got
+        // the page-aligned window. (An aligned offset — the default paging pattern
+        // of incrementing by `limit` — is served exactly, so no note.)
+        {
+          const reqOffset = input.offset ?? 0;
+          const size = input.limit ?? 25;
+          if (reqOffset % size !== 0) {
+            notes.push(
+              `Keyless SAM pagination is page-based (page × ${size}); the requested offset ${reqOffset} was snapped DOWN to the page boundary ${Math.floor(reqOffset / size) * size}. Page through by incrementing offset in multiples of limit (set SAM_GOV_API_KEY for exact row offsets).`,
+            );
+          }
+        }
         notes.push(...enrichmentNotes);
 
         // freshness is surfaced structurally in `data` (the ResponseMeta type
@@ -5654,7 +5669,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "nist_800_53_controls",
     description:
-      "Look up NIST SP 800-53 Rev 5 security & privacy CONTROLS (keyless) — the requirement backbone for FedRAMP / CMMC / RMF compliance work. Retrieve a control by `controlId` (exact, e.g. 'AC-2', 'SC-7', 'AC-2(1)'), a `family` (2-letter code 'AC'/'SC'/'IA' or a name substring 'Access Control'), and/or a `keyword` (case-insensitive substring over title + statement); `limit`/`offset` pagination. Each row: { id (e.g. 'AC-2'), family (e.g. 'AC — Access Control'), title, statement (the labelled requirement prose), guidance (discussion), enhancements:[{id,title}] (e.g. AC-2(1)) }. Complements cve_lookup + cisa_kev_lookup (the vulnerability side) with the CONTROL/requirement side. HONESTY: source is NIST's OFFICIAL OSCAL catalog published at github.com/usnistgov/oscal-content (authoritative first-party data served from GitHub, not a .gov API host — provenance disclosed in _meta); the catalog has no query API so filtering is CLIENT-SIDE and totalAvailable is the EXACT match count; this is the REQUIREMENT text only — applicability depends on the system's FIPS-199 impact baseline (Low/Moderate/High), which the catalog does not encode (disclosed); a download failure or an implausibly-truncated catalog (< 15 families) THROWS (never a fake-empty 'control not found').",
+      "Look up NIST SP 800-53 Rev 5 security & privacy CONTROLS (keyless) — the requirement backbone for FedRAMP / CMMC / RMF compliance work. Retrieve a control by `controlId` (exact, e.g. 'AC-2', 'SC-7', 'AC-2(1)'), a `family` (2-letter code 'AC'/'SC'/'IA' or a name substring 'Access Control'), and/or a `keyword` (case-insensitive substring over title + statement); `limit`/`offset` pagination. Each row: { id (e.g. 'AC-2'), family (e.g. 'AC — Access Control'), title, status ('withdrawn' | null), statement (the labelled requirement prose; NULL for a WITHDRAWN control, never ''), guidance (discussion), incorporatedInto:[control ids that superseded a withdrawn control, e.g. AC-13 → ['AC-2','AU-6']], enhancements:[{id,title}] (e.g. AC-2(1)) }. Complements cve_lookup + cisa_kev_lookup (the vulnerability side) with the CONTROL/requirement side. HONESTY: source is NIST's OFFICIAL OSCAL catalog published at github.com/usnistgov/oscal-content (authoritative first-party data served from GitHub, not a .gov API host — provenance disclosed in _meta); the exact OSCAL version + last-modified are surfaced in _meta (the catalog is fetched live from the MOVING 'main' branch, so control text can shift between point releases, e.g. 5.1.1 → 5.2.0 — cite the version, not just 'Rev 5'); a WITHDRAWN control (status:'withdrawn') has statement:null and is NOT an active requirement (see incorporatedInto for what replaced it); the catalog has no query API so filtering is CLIENT-SIDE and totalAvailable is the EXACT match count; this is the REQUIREMENT text only — applicability depends on the system's FIPS-199 impact baseline (Low/Moderate/High), which the catalog does not encode (disclosed); a download failure or an implausibly-truncated catalog (< 15 families) THROWS (never a fake-empty 'control not found').",
     inputSchema: NistControlsInput,
     handler: (input) => nistControls.searchControls(input),
   }),
@@ -6269,7 +6284,7 @@ export const TOOLS: ToolDef[] = [
   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; 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.",
+      "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 '2023'), 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),
   }),
@@ -6446,7 +6461,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "cbp_border_wait_times",
     description:
-      "Live CBP land-border-port wait times — current commercial-vehicle (and passenger) crossing delays at every US Canadian- and Mexican-border port (keyless; bwt.cbp.gov). The FREIGHT / LOGISTICS situational-awareness lane: per-port commercial-vehicle standard + FAST lane delay (minutes), operational status, open-lane count, and maximum lanes. Filters (optional): `border` (case-insensitive substring, 'Canadian'/'Mexican'), `portName` (substring, e.g. 'Laredo'); `limit`/`offset` pagination. Each row: { portNumber, portName, crossingName, border, portStatus (Open/Closed), asOf, commercialVehicle:{ maxLanes, standard:{operationalStatus, delayMinutes, lanesOpen, updateTime}, fast:{…} } }. HONESTY: this is REAL-TIME operational data — each lane carries its own updateTime (surfaced verbatim; freshness never implied live-to-the-second); delayMinutes/lanesOpen are number|null (a real 0 stays 0; an empty/N/A value — e.g. a closed lane — is null, NEVER a fabricated 0, because a closed lane's delay is UNKNOWN, not zero); the API returns the WHOLE port set so totalAvailable is the EXACT matched-port count; an outage/4xx/timeout THROWS and a non-array body ⇒ schema_drift (never a fake empty).",
+      "Live CBP land-border-port wait times — current commercial-vehicle (freight-truck) crossing delays at every US Canadian- and Mexican-border port (keyless; bwt.cbp.gov). The FREIGHT / LOGISTICS situational-awareness lane: per-port commercial-vehicle standard + FAST lane delay (minutes), operational status, open-lane count, and maximum lanes — passenger/pedestrian lanes are NOT surfaced (freight lane only). Filters (optional, applied CLIENT-SIDE over the full fetched port set — the feed has NO server-side filter; an empty-string value is reported in _meta.filtersDropped, not applied): `border` (case-insensitive substring, 'Canadian'/'Mexican'), `portName` (substring, e.g. 'Laredo'); `limit`/`offset` pagination. Each row: { portNumber, portName, crossingName, border, portStatus (Open/Closed), asOf, commercialVehicle:{ maxLanes, standard:{operationalStatus, delayMinutes, lanesOpen, updateTime}, fast:{…} } }. HONESTY: this is REAL-TIME operational data — each lane carries its own updateTime (surfaced verbatim; freshness never implied live-to-the-second); delayMinutes/lanesOpen are number|null (a real 0 stays 0; an empty/N/A value — e.g. a closed lane — is null, NEVER a fabricated 0, because a closed lane's delay is UNKNOWN, not zero); the API returns the WHOLE port set so totalAvailable is the EXACT matched-port count; an outage/4xx/timeout THROWS and a non-array body ⇒ schema_drift (never a fake empty).",
     inputSchema: CbpBorderWaitInput,
     handler: (input) => cbpBorder.borderWaitTimes(input),
   }),
@@ -6475,7 +6490,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "gsa_perdiem_rates",
     description:
-      "Look up GSA Federal Travel PER-DIEM rates — the max lodging + Meals & Incidental Expenses (M&IE) reimbursement ceilings for official U.S. government travel (api.gsa.gov /travel/perdiem/v2, keyed — DATA_GOV_API_KEY or the shared DEMO_KEY). Input: EITHER `city` (e.g. 'Washington') + `state` (2-letter, e.g. 'DC') OR `zip` (5-digit) — supplying BOTH, or NEITHER, ⇒ invalid_input with 0 fetch; optional `year` (default '2025'). Returns { rates:[{ city, county, state, zip, year, isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd (the API's monthly `value`) is the MAX nightly lodging ceiling for that month — it VARIES SEASONALLY (hence a per-month array), and mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — a genuine 0 is preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (an unrecognized value ⇒ null, never a fabricated false); the months array is preserved AS-IS (never padded to 12). The API returns the COMPLETE rate set (no pagination) ⇒ totalAvailable = the row count, complete:true. A genuine no-match (rates:[]/rate:[]) ⇒ honest empty (returned:0); the API's `errors` field non-null ⇒ invalid_input carrying the message (never a fake empty); a 429 (DEMO_KEY ~10 req/hr, hit quickly) ⇒ rate_limited THROWS; a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON ⇒ schema_drift. DEMO_KEY ~10 req/hr shared ceiling — set DATA_GOV_API_KEY (free at api.data.gov/signup) for 1000/hr. The key rides ONLY in the X-Api-Key header (never the URL/_meta).",
+      "Look up GSA Federal Travel PER-DIEM rates — the max lodging + Meals & Incidental Expenses (M&IE) reimbursement ceilings for official U.S. government travel (api.gsa.gov /travel/perdiem/v2, keyed — DATA_GOV_API_KEY or the shared DEMO_KEY). Input: EITHER `city` (e.g. 'Washington') + `state` (2-letter, e.g. 'DC') OR `zip` (5-digit) — supplying BOTH, or NEITHER, ⇒ invalid_input with 0 fetch; optional `year` (default: the current U.S. federal fiscal year). Returns { rates:[{ city, county, state, zip, year, isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd (the API's monthly `value`) is the MAX nightly lodging ceiling for that month — it VARIES SEASONALLY (hence a per-month array), and mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — a genuine 0 is preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (an unrecognized value ⇒ null, never a fabricated false); the months array is preserved AS-IS (never padded to 12). The API returns the COMPLETE rate set (no pagination) ⇒ totalAvailable = the row count, complete:true. A genuine no-match (rates:[]/rate:[]) ⇒ honest empty (returned:0); the API's `errors` field non-null ⇒ invalid_input carrying the message (never a fake empty); a 429 (DEMO_KEY ~10 req/hr, hit quickly) ⇒ rate_limited THROWS; a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON ⇒ schema_drift. DEMO_KEY ~10 req/hr shared ceiling — set DATA_GOV_API_KEY (free at api.data.gov/signup) for 1000/hr. The key rides ONLY in the X-Api-Key header (never the URL/_meta).",
     inputSchema: GsaPerdiemRatesInput,
     handler: (input) => gsaPerdiem.perdiemRates(input),
   }),
@@ -6510,7 +6525,7 @@ export const TOOLS: ToolDef[] = [
   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).",
+      "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` (NOTE: /filings/ has NO server-side agency filter — the LDA API silently ignores it, so it is reported in _meta.filtersDropped and NOT applied; government entities are nested per activity in lobbyingActivities[].governmentEntities), `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),
   }),
@@ -6618,6 +6633,7 @@ async function main() {
         name: t.name,
         description: t.description,
         inputSchema: zodToJsonSchema(t.inputSchema),
+        annotations: toolAnnotations(t.name),
       })),
     };
   });
@@ -6793,10 +6809,57 @@ export async function runTool(
   throw new Error(`Unknown tool: ${name}`);
 }
 
+// ─── MCP tool annotations ────────────────────────────────────────────────────
+// Every tool advertises a human-friendly `title` plus behaviour hints, per the MCP
+// spec and the Anthropic Connectors Directory requirement (title + readOnlyHint).
+// EVERY tool in this server is strictly READ-ONLY (queries public data; none mutate
+// upstream state) and OPEN-WORLD (calls external government/public APIs), so those
+// two hints are uniform. `title` is derived from the tool name via a source-prefix
+// map so e.g. `sam_search_opportunities` → "SAM.gov: Search Opportunities".
+const TOOL_SOURCE_LABELS: Record<string, string> = {
+  sam: "SAM.gov", usas: "USAspending", edgar: "SEC EDGAR", fdic: "FDIC", cms: "CMS",
+  treasury: "Treasury", regulations: "Regulations.gov", openfda: "openFDA",
+  govinfo: "GovInfo", fema: "FEMA", far: "FAR/DFARS", ecfr: "eCFR", census: "Census",
+  clinicaltrials: "ClinicalTrials.gov", bls: "BLS", socrata: "Socrata", opengov: "OpenGov",
+  nsf: "NSF", nonprofit: "Nonprofit", nhtsa: "NHTSA", gsa: "GSA", grants: "Grants.gov",
+  fred: "FRED", fac: "FAC", echo: "EPA ECHO", dol: "DOL", congress: "Congress.gov",
+  ckan: "data.gov", bonfire: "Bonfire", arcgis: "ArcGIS", sba: "SBA", ofac: "OFAC",
+  nws: "NWS", nppes: "NPPES", nist: "NIST", nih: "NIH", lda: "Senate LDA", hts: "USITC HTS",
+  bea: "BEA", cbp: "CBP", cpsc: "CPSC", nvd: "NVD", courtlistener: "CourtListener",
+  fpds: "FPDS", gao: "GAO", epa: "EPA", nsn: "NSN",
+};
+const TOOL_ACRONYMS = new Set([
+  "naics", "psc", "cfda", "npi", "cve", "csv", "id", "url", "rss", "api", "hts", "sic",
+  "dmepos", "cbp", "sam", "fdic", "epa", "ofac", "far", "dfars", "irs", "usc", "cfr",
+]);
+export function humanizeToolTitle(name: string): string {
+  const tokens = name.split("_");
+  // `fed_register_*` is a two-token source label.
+  let source = tokens[0] ?? "";
+  let rest = tokens.slice(1);
+  if (source === "fed" && tokens[1] === "register") {
+    source = "fed_register";
+    rest = tokens.slice(2);
+  }
+  const label = source === "fed_register" ? "Federal Register" : TOOL_SOURCE_LABELS[source];
+  const words = (label ? rest : tokens)
+    .map((w) => (TOOL_ACRONYMS.has(w) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(" ");
+  return label ? (words ? `${label}: ${words}` : label) : words;
+}
+/** Uniform MCP annotations for a tool: derived title + read-only / open-world hints. */
+export function toolAnnotations(name: string): {
+  title: string;
+  readOnlyHint: true;
+  openWorldHint: true;
+} {
+  return { title: humanizeToolTitle(name), readOnlyHint: true, openWorldHint: true };
+}
+
 /**
  * Hand-rolled Zod → JSON Schema converter (subset we use).
  */
-function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
+export function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
   const def = (schema as unknown as { _def: { typeName: string } })._def;
   const tn = def.typeName;
   const description = (schema as unknown as { description?: string }).description;
@@ -6848,6 +6911,19 @@ function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
     const innerSchema = zodToJsonSchema(inner);
     return description ? { ...innerSchema, description } : innerSchema;
   }
+  if (tn === "ZodEffects") {
+    // .refine() / .superRefine() / .transform() wrap the REAL schema at
+    // `_def.schema` (used for cross-field rules like "npi OR state required").
+    // Without this branch these fall through to the {type:"string"} default,
+    // publishing a degenerate object-less inputSchema that a schema-driven MCP
+    // client cannot construct a call against — even though the runtime Zod still
+    // demands the full object. Unwrap so the published schema keeps its real
+    // properties / required / enums.
+    const inner = (schema as unknown as { _def: { schema: z.ZodTypeAny } })._def
+      .schema;
+    const innerSchema = zodToJsonSchema(inner);
+    return description ? { ...innerSchema, description } : innerSchema;
+  }
   return { type: "string", ...(description ? { description } : {}) };
 }
 

package/src/socrata.ts

@@ -194,6 +194,36 @@ export const SOCRATA_DOMAINS = [
   "data.lacity.org", // Los Angeles CA (.org, official) — e.g. hf3r-utnq (RAMP Open Bid Opportunities — live bids)
   "data.ramseycountymn.gov", // Ramsey County MN (.gov) — e.g. iu7r-dzmj (Solicitations & Addenda, with due_date/download_url ~516)
   "data.richmondgov.com", // Richmond VA (.com, official) — e.g. xqn7-jvv2 (City Contracts: contract_value/supplier/procurement_type ~1,387)
+  // ── County/city procurement sweep, wave 2 (loop cycle 19, 2026-07-20). Same
+  //    federated-catalog mining + host-scoped count(*) + /resource 200 bare-array
+  //    verification. All large real checkbook/PO/vendor-payment datasets. ──
+  "opendata.howardcountymd.gov", // Howard County MD (.gov) — e.g. mesh-jggc (Vendors Receiving Payments $30k+ ~35k)
+  "data.providenceri.gov", // Providence RI (.gov) — e.g. 425y-pm5m (City & School Dept Purchase Orders ~228k)
+  "fiscalfocus.pittsburghpa.gov", // Pittsburgh PA (.gov) — e.g. t8t2-4b5n (Checkbook Data ~1.01M)
+  "data.coloradosprings.gov", // Colorado Springs CO (.gov) — e.g. yn6y-xikx (Open Checkbook Vendors ~19k)
+  "data.framinghamma.gov", // Framingham MA (.gov) — e.g. cqve-ehkr (Checkbook ~324k)
+  "data.fultoncountyga.gov", // Fulton County GA (.gov) — e.g. mxhc-krcg (Vendor Payments/disbursements ~217k)
+  "atlanta.data.socrata.com", // City of Atlanta GA (Socrata-hosted official portal) — e.g. jmke-icfi (Open Checkbook Ledger ~1.78M)
+  "opendata.cityofmesquite.com", // Mesquite TX (.com, official) — e.g. 6tva-azs5 (Check Register ~144k)
+  // ── County/city procurement sweep, wave 3 (loop cycle 20, 2026-07-20). Expanded
+  //    federated-catalog queries (rfp/rfq/disbursement/expenditure/commodity) +
+  //    offset paging. Provenance confirmed via /api/views attribution or the gov
+  //    domain itself; hosts with only an individual-name attribution on a generic
+  //    *.data.socrata.com subdomain (washoe, newcastle) were DEFERRED. ──
+  "datahub.usac.org", // USAC E-Rate (.org, same org as opendata.usac.org) — e.g. 39tn-hjzv (E-Rate Open Competitive Bidding, FCC Form 470 — schools/libraries LIVE bids ~2.2M)
+  "performance.ci.janesville.wi.us", // City of Janesville WI (.us official municipal domain) — e.g. fd4q-2kma (Open Expenditures Ledger ~1.0M)
+  "datahub.austintexas.gov", // Austin TX secondary hub (.gov) — e.g. 3ebq-e9iz (Purchase Order Quantity/Price detail, commodity/goods procurements ~318k)
+  "cthru.data.socrata.com", // Commonwealth of Massachusetts, Office of the Comptroller — CTHRU statewide spending (attribution-confirmed) — e.g. kv7m-35wn (Budget/Actual + spending authorizations ~48k)
+  "data.macoupincountyil.gov", // Macoupin County IL (.gov) — e.g. wysn-7qcg (Open Expenditures Ledger ~156k)
+  "data.oaklandca.gov", // Oakland CA (.gov) — e.g. 4ewt-5m6f (budget expenditures ~66k)
+  "data.princegeorgescountymd.gov", // Prince George's County MD (.gov) — e.g. csi4-9jzc (Spending Information: payee_name/agency/amount ~62k)
+  "data.cstx.gov", // College Station TX (.gov) — e.g. i5cx-63zy (Open Budget Expenditures ~42k)
+  "datahub.transportation.gov", // US DOT secondary hub (.gov) — e.g. 255k-mnvp (Disbursements by States for Highways SF-2 ~15k)
+  // ── County/city procurement sweep, wave 4 / tail (loop cycle 21, 2026-07-20).
+  //    Diminishing returns (most remaining catalog hits are Canada/AU, demo/test,
+  //    duplicates, or off-theme); these two are the clean US wins. ──
+  "citydata.mesaaz.gov", // Mesa AZ secondary hub (.gov, attr "Office of Management and Budget") — e.g. vdg8-dx96 (City Expenditures ~15.4M)
+  "data.weho.org", // City of West Hollywood CA (.org, official portal) — e.g. atdr-sk64 (Active Contracts: contract_number/contractor_name/status/type — live/current ~1,030)
 ] as const;
 
 export type SocrataDomain = (typeof SOCRATA_DOMAINS)[number];
@@ -208,14 +238,21 @@ const CATALOG_URL = `https://${CATALOG_HOST}/api/catalog/v1`;
 // regex `$` alone would admit ("abcd-1234\n" passes /…$/ in JS).
 const DATASET_ID_RE = /^[a-z0-9]{4}-[a-z0-9]{4}$/;
 
-// D2 — an AGGREGATE $select projection. Matches a SoQL aggregate function
-// (count/sum/avg/min/max) applied via `fn(` — the `\b…\s*\(` shape avoids false
-// hits on column names like `max_temperature` (no paren) or `xmax(` (no word
-// boundary) — OR an explicit `group by`/`$group`. Case-insensitive. When the
-// caller's own $select is aggregate, the count(*) companion is skipped (its
-// raw-row total would be false for aggregate result rows). See `query`.
+// D2 — a cardinality-CHANGING $select projection: ANY function call (`word(` —
+// count/sum/avg/min/max/median/stddev/count_distinct/percentile/…), the bare
+// `distinct` keyword, or an explicit `group by`/`$group`. Case-insensitive. The
+// `\b\w+\s*\(` shape matches a real function CALL (a word followed by a paren),
+// never a plain column name like `max_temperature` (no paren). When the caller's
+// own $select is one of these, the result rows are NOT raw records, so the
+// count(*) companion (which counts SOURCE rows) would be a FALSE total — e.g.
+// `$select=distinct state` returns 54 rows but count(*) is 137,700 → a wrong total
+// AND a hasMore livelock (paging forever over empty pages). So we skip the
+// companion (totalAvailable:null + page-fullness hasMore). A plain comma-separated
+// column list is NOT matched and keeps its real count(*) total. (A per-row
+// function like `upper(x)` also matches → a conservative null-total, an honest
+// "unknown" rather than risking a wrong one.) See `query`.
 const AGGREGATE_SELECT_RE =
-  /\b(?:count|sum|avg|min|max)\s*\(|\bgroup\s+by\b|\$group\b/i;
+  /\b\w+\s*\(|\bdistinct\b|\bgroup\s+by\b|\$group\b/i;
 
 // ─── HONESTY-CRITICAL coercions (null, never 0, for absent) ───────
 // `num`/`str` are the shared, audited null-never-0 coercions in ./coerce.js

package/src/usaspending.ts

@@ -1468,7 +1468,7 @@ export async function searchRecompetes(args: {
     awardId: string;
     generatedInternalId: string;
     incumbent: string;
-    amount: number;
+    amount: number | null;
     currentEndDate: string;
     daysUntilCurrentEnd: number;
     potentialEndDate?: string | null;
@@ -1515,8 +1515,11 @@ export async function searchRecompetes(args: {
         pastWindow = true;
         break;
       }
-      const amount = row["Award Amount"] ?? 0;
-      if (amount < minAwardValue) continue;
+      // Filter/sort on a numeric view (absent = 0 for COMPARISON only), but EMIT the
+      // raw value below so an ABSENT amount stays null — P3 null-never-0, matching every
+      // sibling search tool ("an ABSENT Award Amount → null, NEVER a fabricated $0").
+      const amountNum = row["Award Amount"] ?? 0;
+      if (amountNum < minAwardValue) continue;
       const potentialEnd = includePotentialEnd
         ? row["Period of Performance Potential End Date"] ?? null
         : undefined;
@@ -1529,7 +1532,7 @@ export async function searchRecompetes(args: {
         awardId: row["Award ID"] ?? "",
         generatedInternalId: row.generated_internal_id ?? "",
         incumbent: row["Recipient Name"] ?? "",
-        amount,
+        amount: row["Award Amount"] ?? null,
         currentEndDate: end as string,
         daysUntilCurrentEnd: d,
         ...(includePotentialEnd
@@ -1557,7 +1560,10 @@ export async function searchRecompetes(args: {
   results.sort((a, b) => {
     if (a.daysUntilCurrentEnd !== b.daysUntilCurrentEnd)
       return a.daysUntilCurrentEnd - b.daysUntilCurrentEnd;
-    if (b.amount !== a.amount) return b.amount - a.amount;
+    // A null amount (P3 — absent, not $0) sorts as 0 for this tiebreak ONLY; it is
+    // never surfaced as 0 in the output.
+    const av = a.amount ?? 0, bv = b.amount ?? 0;
+    if (bv !== av) return bv - av;
     return a.awardId.localeCompare(b.awardId);
   });
 
@@ -1570,10 +1576,15 @@ export async function searchRecompetes(args: {
   // (early-stop fired). If the scan budget truncated, it is unknown → null,
   // and the returned set is a lower bound.
   const totalAvailable = scanTruncated ? null : totalInWindow;
-  const nextOffset = startIdx + pageSize;
-  const hasMore = scanTruncated
-    ? true // more may exist beyond the scanned pages
-    : nextOffset < totalInWindow;
+  // `nextOffset` may ONLY advance into rows we ACTUALLY scanned. The un-scanned
+  // remainder (scanTruncated) is NOT offset-reachable: paging past totalInWindow
+  // re-runs the whole bounded scan and returns EMPTY pages forever — the
+  // "re-fetch the SAME page" livelock every other tool in this module emits
+  // nextOffset:null to avoid. So advance the cursor only while more SCANNED rows
+  // remain; signal the un-scanned tail via hasMore:true + nextOffset:null (the
+  // notes already tell the caller to raise scanBudgetPages, not to paginate).
+  const moreInScanned = startIdx + pageSize < totalInWindow;
+  const hasMore = moreInScanned || scanTruncated;
   const truncated = hasMore || scanTruncated;
 
   const notes: string[] = [
@@ -1612,7 +1623,7 @@ export async function searchRecompetes(args: {
     pagination: {
       offset: startIdx,
       limit: pageSize,
-      nextOffset: hasMore ? nextOffset : null,
+      nextOffset: moreInScanned ? startIdx + pageSize : null,
       hasMore,
     },
     filtersApplied,