@cliwant/mcp-sam-gov 1.15.0 → 1.17.0

package/src/server.ts

@@ -116,10 +116,21 @@ import {
   toolNotLoadedEnvelope,
 } from "./toolsets.js";
 
+// Where a state-level bid feed lives when it is NOT on OpenGov or Bonfire. Measured,
+// not cosmetic: asked for "Illinois state solicitations", an eval agent searched
+// opengov_list_governments then bonfire_list_organizations, found no state-level IL
+// portal in either, and never reached data.illinois.gov 6rb8-ntpm (in one run it answered
+// with generic portal advice after a single call; in another it ran out of budget). These are
+// the tools an agent reaches for when it thinks "solicitations", so the pointer goes
+// here rather than only on socrata_query, which it never opened.
+const STATE_BID_FEEDS_POINTER =
+  "STATE-LEVEL bid feeds on open-data portals are NOT in this directory: TX TxDOT lettings, advertised and taking bids = socrata_query data.texas.gov qh8x-rm8r; IL CDB capital bids that are ANTICIPATED and NOT YET POSTED = socrata_query data.illinois.gov 6rb8-ntpm (~48 rows, not IL's full register). Map: resource samgov://data-map/state-local.";
+
+
 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.15.0";
+const SERVER_VERSION = "1.17.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -751,13 +762,19 @@ const WageSearchInput = z.object({
     .string()
     .optional()
     .describe(
-      "2-letter USPS state code (e.g. 'VA'), applied SERVER-SIDE. A full name is applied client-side instead.",
+      "2-letter USPS state code (e.g. 'IL'), applied SERVER-SIDE. A full name is applied client-side instead.",
     ),
   county: z
     .string()
     .optional()
     .describe(
-      "County name (substring match), applied CLIENT-SIDE over the fetched page only (the API has no county filter).",
+      "County name (substring match, e.g. 'Cook'). When given, ALL pages for the state are scanned before filtering so no WDs are missed.",
+    ),
+  constructionType: z
+    .enum(["Building", "Residential", "Heavy", "Highway"])
+    .optional()
+    .describe(
+      "DBA construction type (Building | Residential | Heavy | Highway). This is the PRIMARY key for a Davis-Bacon lookup: pass state + county + constructionType to pinpoint the correct WD. E.g. Building = federal buildings, schools; Heavy = bridges, utilities; Highway = roads.",
     ),
   query: z
     .string()
@@ -770,8 +787,8 @@ const WageSearchInput = z.object({
     .boolean()
     .optional()
     .describe("Only standard (non-non-standard) WDs (default true)."),
-  limit: z.number().min(1).max(50).optional().describe("Page size (default 20, max 50)."),
-  page: z.number().min(0).optional().describe("0-based page index (default 0)."),
+  limit: z.number().min(1).max(50).optional().describe("Page size (default 20, max 50). Ignored when county or constructionType is given — a full-state scan is performed instead."),
+  page: z.number().min(0).optional().describe("0-based page index (default 0). Ignored when county or constructionType is given — a full-state scan is performed instead."),
 });
 
 const WageRatesInput = z.object({
@@ -1965,7 +1982,14 @@ const SocrataQueryInput = z.object({
   select: z
     .string()
     .optional()
-    .describe("Optional SoQL $select (column projection / aggregate), e.g. 'agency,SUM(amount)'."),
+    .describe(
+      "Optional SoQL $select (column projection or aggregate). " +
+      "For a TOTAL: 'sum(amount)' (add a where for vendor/fiscal-year filter). " +
+      "For a TOP-N ranking: 'vendor_name, sum(amount) as total' — pair with order='total DESC'. " +
+      "Any SoQL function call (sum/count/avg/min/max) or 'distinct' activates aggregate mode: " +
+      "totalAvailable becomes null (no raw-row total for aggregates) and the count(*) companion is skipped. " +
+      "NEVER sum rows from one page to get a total — always use an aggregate select.",
+    ),
   where: z
     .string()
     .optional()
@@ -2003,7 +2027,7 @@ const SocrataDiscoverDatasetsInput = z.object({
   q: z
     .string()
     .min(1)
-    .describe("Keyword(s) to find datasets, e.g. 'procurement', 'vendor payments', 'checkbook'."),
+    .describe("TOPIC words only, e.g. 'solicitations', 'contract', 'vendor payments', 'checkbook'. Put the JURISDICTION in `domain`, never in q: every q term must match and dataset titles rarely repeat their place name, so q='Illinois solicitations' returns 0 while domain=data.illinois.gov q='solicitations' finds the dataset."),
   domain: SocrataDomainEnum.optional().describe(
     "Optional: scope discovery to ONE portal; omit to search all. The catalog does not index every host (USAC returns 0); those stay queryable via socrata_query with a known 4x4. " +
     "Jurisdiction of non-obvious hosts: cthru.data.socrata.com=MASSACHUSETTS statewide (CTHRU); atlanta.data.socrata.com=Atlanta GA; controllerdata.lacity.org+data.lacity.org=Los Angeles; www.dallasopendata.com=Dallas TX; data.brla.gov=Baton Rouge LA; data.kcmo.org=Kansas City MO; data.cstx.gov=College Station TX; data.weho.org=West Hollywood CA; opendata.usac.org+datahub.usac.org=federal USAC E-rate. data.colorado.gov's procurement data is CITY OF DENVER, not CO state.",
@@ -3082,7 +3106,7 @@ const BonfireSearchOpportunitiesInput = z.object({
 const OpenCheckbookSearchInput = z.object({
   portal: z
     .enum(openCheckbook.OPEN_CHECKBOOK_PORTALS.map((p) => p.key) as [string, ...string[]])
-    .describe("The curated Open-Checkbook portal (SSRF allowlist enum). 'sd' = State of South Dakota Open Checkbook (~740,980 vendor payments, ~$8.41B, ~3 most-recent fiscal years)."),
+    .describe("The curated Open-Checkbook portal (SSRF allowlist enum). 'sd' = State of South Dakota Open Checkbook (~740,980 vendor payments, ~$8.41B, ~3 most-recent fiscal years). 'ak' = State of Alaska Open Checkbook (41,751 payments, $1.18B — FY2026 ONLY; FY2019–2025 return count:0 meaning not published, NOT zero spend)."),
   year: z.string().min(1).max(40).optional().describe("Fiscal-year filter (EXACT match), e.g. '2025'. Default 'All Years' = the exposed ~3-year window (NOT full history)."),
   vendor: z.string().min(1).max(200).optional().describe("Vendor name filter (EXACT match, e.g. 'US BANK NA' → 917). A partial/misspelled value returns an honest count:0."),
   org: z.string().min(1).max(200).optional().describe("Department filter (org1, EXACT match, e.g. 'TRANSPORTATION' → 109,887)."),
@@ -4461,7 +4485,7 @@ const GsaPerdiemRatesInput = z
       .regex(/^\d{4}$/)
       .optional()
       .describe(
-        "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).",
+        "U.S. federal fiscal year number (Oct 1–Sep 30). Default: current FY at call time. IMPORTANT: October 2026 = FY2027; September 2026 = FY2026. To get October 2026 rates, pass year='2027'. Validated ^\d{4}$ (it rides in the request path).",
       ),
   })
   .describe(
@@ -4617,11 +4641,16 @@ const LdaSearchFilingsInput = z.object({
 // 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({
+  party: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Company or person name to match as an ACTUAL PARTY — builds caseName:\"…\" fielded query. A bare company name in `query` matches text mentions (~5,954 for 'Lockheed Martin'); `party` finds cases where the company is actually named as a party (~327). Use `party` for vendor/contractor vetting; use `query` for full-text topic search."),
   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."),
+    .describe("Additional full-text query (maps to q) — topic keywords such as 'False Claims Act' or 'bid protest'. Combined with caseName:\"…\" when `party` is also given. A bare company name here matches text mentions, not actual-party cases — use `party` for that."),
   court: z
     .string()
     .regex(/^[a-z0-9]+$/)
@@ -4654,6 +4683,53 @@ const CourtlistenerSearchOpinionsInput = z.object({
     .describe("Sort order (maps to order_by), default 'dateFiled desc' (most recent first). E.g. 'dateFiled asc', 'score desc'."),
 });
 
+// ─── CourtListener RECAP dockets (type=r) ────────────────────────
+// ADR-0064. FCA/qui tam matters are DOCKETS — they rarely produce published opinions
+// so they are invisible to type=o. suitNature:"…" is a REAL fielded filter on dockets.
+// Same SSRF / auth / cursor / provenance guards as opinions.
+const CourtlistenerSearchDocketsInput = z.object({
+  party: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Company or person name to match as an ACTUAL PARTY — builds caseName:\"…\" fielded query. Use for vendor/contractor due-diligence (FCA, False Claims Act, qui tam). E.g. 'Lockheed Martin' → ~9 FCA dockets."),
+  query: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Additional free-text keywords (combined with caseName:\"…\" when `party` is given). E.g. 'qui tam' or 'whistleblower'."),
+  natureOfSuit: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Nature-of-suit filter — builds suitNature:\"…\" fielded query (THIS IS A REAL DOCKET FIELD, not folded into q). E.g. 'False Claims' to find FCA/qui tam dockets. Disclosed in _meta.notes."),
+  court: z
+    .string()
+    .regex(/^[a-z0-9]+$/)
+    .optional()
+    .describe("CourtListener court id (lowercase alphanumerics ^[a-z0-9]+$), e.g. 'gand' (N.D. Ga.), 'flmd' (M.D. Fla.), 'cafc'. Filters to one court."),
+  dateFiledAfter: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe("Only dockets filed on/after this ISO date (→ filed_after), e.g. '2015-01-01'."),
+  dateFiledBefore: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe("Only dockets filed on/before this ISO date (→ filed_before), e.g. '2024-12-31'."),
+  order: z
+    .string()
+    .min(1)
+    .default("dateFiled desc")
+    .describe("Sort order (maps to order_by), default 'dateFiled desc'. E.g. 'dateFiled asc'."),
+  cursor: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Opaque continuation token — pass back _meta.nextCursor from the previous page."),
+});
+
 // ─── 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
@@ -5639,7 +5715,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "sam_search_wage_determinations",
     description:
-      "Find the Service Contract Act (SCA) or Davis-Bacon (DBA) wage determination(s) governing a locality (keyless SAM SGS). Filter by coverage (sca|dba), state (2-letter, server-side), county (client-side), or WD number/title. Returns the structured WD list; follow with sam_get_wage_rates to read the rate table. NOTE: `query` matches WD number/title only, NOT occupation.",
+      "Find the Service Contract Act (SCA) or Davis-Bacon Act (DBA) wage determination(s) for a locality (keyless SAM SGS). For a Davis-Bacon lookup pass state + county + constructionType (e.g. 'IL', 'Cook', 'Building') — the tool scans ALL pages for the state so no WDs are missed, ranks single-county WDs first (the most specific match), and reports real match counts. Then call sam_get_wage_rates on the top result to read the rate table. SCA: pass state + county. constructionType is DBA-only: Building (federal buildings/schools), Residential, Heavy (bridges/utilities), Highway (roads). NOTE: `query` matches WD number/title only, NOT occupation.",
     inputSchema: WageSearchInput,
     handler: (input) => pricing.searchWageDeterminations(input),
   }),
@@ -5843,7 +5919,7 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "socrata_query",
     description:
-      "Query rows from an allowlisted Socrata/SODA open-data portal (keyless; ~a dozen US state portals + USAC E-rate on one identical API — state spend/checkbook/contract/vendor-payment datasets). State procurement mirrors: NY ehig-g5x3, NJ ubnu-tqu7, WA s8d5-pj78, MA cthru.data.socrata.com pegc-naaa (~49M payment rows). Full map: read resource samgov://data-map/state-local. Input `domain` (curated allowlist enum — the SSRF host guard), `datasetId` (4x4, from socrata_discover_datasets), optional SoQL `select`/`where`/`order`/`q`, `limit` (≤1000, def 100), `offset`, `withTotal` (def true). HONESTY: SODA's row response has no total, so a count(*) companion supplies an exact totalAvailable; if it fails the rows still return with totalAvailable:null + a note (hasMore is then inferred from page-fill, never a false complete). Genuine-empty ⇒ complete:true/total:0; an outage/400/404 THROWS (never a fake empty). Value fields are strings.",
+      "Query rows from an allowlisted Socrata/SODA open-data portal (keyless; ~a dozen US state portals + USAC E-rate on one identical API — state spend/checkbook/contract/vendor-payment datasets). State procurement mirrors: NY ehig-g5x3, NJ ubnu-tqu7, WA s8d5-pj78, MA cthru.data.socrata.com pegc-naaa (~49M payment rows). Full map: read resource samgov://data-map/state-local. Input `domain` (curated allowlist enum — the SSRF host guard), `datasetId` (4x4, from socrata_discover_datasets), optional SoQL `select`/`where`/`order`/`q`, `limit` (≤1000, def 100), `offset`, `withTotal` (def true). AGGREGATES: for a grand total pass select='sum(amount)' with a where filter; for top-N vendors pass select='vendor_name, sum(amount) as total' with order='total DESC' — these return the final answer directly, NOT a page to manually sum. HONESTY: SODA's row response has no total, so a count(*) companion supplies an exact totalAvailable; if it fails the rows still return with totalAvailable:null + a note (hasMore is then inferred from page-fill, never a false complete). Genuine-empty ⇒ complete:true/total:0; an outage/400/404 THROWS (never a fake empty). Value fields are strings.",
     inputSchema: SocrataQueryInput,
     handler: (input) => socrata.query(input),
   }),
@@ -6202,33 +6278,33 @@ export const TOOLS: ToolDef[] = [
   defineTool({
     name: "opengov_list_governments",
     description:
-      "List the government portals on OpenGov Procurement (formerly ProcureNow) — the directory for opengov_search_solicitations (keyless; api.procurement.opengov.com). OpenGov Procurement hosts the live open-solicitation portals of 525+ US state/local governments (cities, counties, school & special districts across 42 states + DC). The WHOLE directory arrives in ONE keyless GET and is filtered client-side: `state` (2-letter), `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Only ACTIVE, non-internal portals are returned. Output: { governments:[{ code, name, city, state, website }] } + honest _meta. Feed a result's `code` to opengov_search_solicitations. HONESTY: this consumes ONLY the anonymous endpoints the public portal itself calls (the official key-gated api-key API is NOT used) — genuinely keyless; totalAvailable is the EXACT filtered portal count (never the page length); a 429/5xx/timeout THROWS (never a fake empty); a non-array body ⇒ schema_drift.",
+      "List the government portals on OpenGov Procurement (formerly ProcureNow) — the directory for opengov_search_solicitations (keyless; api.procurement.opengov.com). OpenGov Procurement hosts the live open-solicitation portals of 525+ US state/local governments (cities, counties, school & special districts across 42 states + DC). The WHOLE directory arrives in ONE keyless GET and is filtered client-side: `state` (2-letter), `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Only ACTIVE, non-internal portals are returned. Output: { governments:[{ code, name, city, state, website }] } + honest _meta. Feed a result's `code` to opengov_search_solicitations. HONESTY: this consumes ONLY the anonymous endpoints the public portal itself calls (the official key-gated api-key API is NOT used) — genuinely keyless; totalAvailable is the EXACT filtered portal count (never the page length); a 429/5xx/timeout THROWS (never a fake empty); a non-array body ⇒ schema_drift." + " " + STATE_BID_FEEDS_POINTER,
     inputSchema: OpengovListGovernmentsInput,
     handler: (input) => opengov.listGovernments(input),
   }),
   defineTool({
     name: "opengov_search_solicitations",
     description:
-      "List a government's public solicitations on OpenGov Procurement (keyless; api.procurement.opengov.com, POST /project/list with the required publicView gate). Input `governmentCode` (the portal slug from opengov_list_governments, e.g. 'santacruzca', 'orlando', 'u-46'; REQUIRED), `limit`(1..100)/`offset`. Returns { governmentCode, solicitations:[{ id, title, solicitationNumber, status, type, department, releaseDate, proposalDeadline, contactName, link }] } + honest _meta. ★STATUS: `status` is surfaced VERBATIM — **open = currently ACCEPTING responses**; pending/evaluation/closed are ALSO returned (publicView shows all public projects), so filter status==='open' for live bids. `link` is the public portal page. HONESTY: totalAvailable = the API's `count` = the org's TOTAL public-project count (all statuses), NEVER the page length and NOT an open-only count (a note discloses this); pagination is the API's fixed page (offset is snapped to the page boundary, disclosed); a genuine no-match ⇒ complete:true/returned:0; a 429/5xx/timeout THROWS (never a fake empty); a non-array `projects` ⇒ schema_drift; a bad `governmentCode` ⇒ invalid_input pre-fetch. Genuinely keyless (the key-gated official API is NOT used).",
+      "List a government's public solicitations on OpenGov Procurement (keyless; api.procurement.opengov.com, POST /project/list with the required publicView gate). Input `governmentCode` (the portal slug from opengov_list_governments, e.g. 'santacruzca', 'orlando', 'u-46'; REQUIRED), `limit`(1..100)/`offset`. Returns { governmentCode, solicitations:[{ id, title, solicitationNumber, status, type, department, releaseDate, proposalDeadline, contactName, link }] } + honest _meta. ★STATUS: `status` is surfaced VERBATIM — **open = currently ACCEPTING responses**; pending/evaluation/closed are ALSO returned (publicView shows all public projects), so filter status==='open' for live bids. `link` is the public portal page. HONESTY: totalAvailable = the API's `count` = the org's TOTAL public-project count (all statuses), NEVER the page length and NOT an open-only count (a note discloses this); pagination is the API's fixed page (offset is snapped to the page boundary, disclosed); a genuine no-match ⇒ complete:true/returned:0; a 429/5xx/timeout THROWS (never a fake empty); a non-array `projects` ⇒ schema_drift; a bad `governmentCode` ⇒ invalid_input pre-fetch. Genuinely keyless (the key-gated official API is NOT used)." + " " + STATE_BID_FEEDS_POINTER,
     inputSchema: OpengovSearchSolicitationsInput,
     handler: (input) => opengov.searchSolicitations(input),
   }),
   // ━━━ Bonfire (Euna) — keyless per-org open-opportunity RSS (SLED bids) ━━━
   // SLED bid campaign. Thousands of US state/local govs on Bonfire expose a keyless
-  // RSS of open opportunities. Ships a curated 195-org live-verified seed directory
+  // RSS of open opportunities. Ships a curated 187-org live-verified seed directory
   // (Bonfire's authoritative org API is auth-gated → out of bounds). Fixed-suffix
   // SSRF (.bonfirehub.com). RSS = the complete open set (totalAvailable honest).
   defineTool({
     name: "bonfire_list_organizations",
     description:
-      "List US governments on the Bonfire (Euna) eProcurement platform — the directory for bonfire_search_opportunities (keyless). Bonfire hosts thousands of US state/local governments' open-bid portals, each with a keyless RSS feed. Filter the curated seed by `state` (2-letter) / `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Output: { organizations:[{ org, name, state }] }. Feed a result's `org` to bonfire_search_opportunities. ★HONESTY: this is a CURATED, live-verified SEED of 195 US orgs — Bonfire has NO keyless org-list API (its authoritative directory is auth-gated, out of bounds), and Euna markets up to ~900 US orgs, so the seed is PARTIAL (disclosed in _meta); probe `{slug}.bonfirehub.com/opportunities/rss` to extend. totalAvailable = the exact filtered seed count.",
+      "List US governments on the Bonfire (Euna) eProcurement platform — the directory for bonfire_search_opportunities (keyless). Bonfire hosts thousands of US state/local governments' open-bid portals, each with a keyless RSS feed. Filter the curated seed by `state` (2-letter) / `query` (case-insensitive name substring); `limit`(1..200)/`offset`. Output: { organizations:[{ org, name, state }] }. Feed a result's `org` to bonfire_search_opportunities. ★HONESTY: this is a CURATED, live-verified SEED of 187 US orgs — Bonfire has NO keyless org-list API (its authoritative directory is auth-gated, out of bounds), and Euna markets up to ~900 US orgs, so the seed is PARTIAL (disclosed in _meta); probe `{slug}.bonfirehub.com/opportunities/rss` to extend. totalAvailable = the exact filtered seed count." + " " + STATE_BID_FEEDS_POINTER,
     inputSchema: BonfireListOrganizationsInput,
     handler: (input) => bonfire.listOrganizations(input),
   }),
   defineTool({
     name: "bonfire_search_opportunities",
     description:
-      "List a government's currently-OPEN solicitations on Bonfire (keyless; {org}.bonfirehub.com/opportunities/rss, RSS 2.0). Input `org` (the subdomain slug from bonfire_list_organizations, e.g. 'harriscountytx', 'broward', 'u-46'; REQUIRED), `limit`(1..200)/`offset`. Returns { org, opportunities:[{ referenceNumber, name, description, closeDate, link, pubDate }] } + honest _meta. HONESTY: the RSS is the COMPLETE set of the org's currently-open opportunities (no server pagination), so totalAvailable = the exact open-opportunity count (never a page length) and this tool pages over it client-side; an empty feed (returned 0) means no open opportunities right now (honest empty, complete:true); `closeDate` is parsed best-effort from the description; a 429/5xx/404/timeout THROWS (never a fake empty); a 200 non-RSS body ⇒ schema_drift; a bad `org` ⇒ invalid_input pre-fetch. Fixed-suffix SSRF (.bonfirehub.com) + redirect:error. Keyless (Bonfire's auth-gated directory API is NOT used).",
+      "List a government's currently-OPEN solicitations on Bonfire (keyless; {org}.bonfirehub.com/opportunities/rss, RSS 2.0). Input `org` (the subdomain slug from bonfire_list_organizations, e.g. 'harriscountytx', 'broward', 'u-46'; REQUIRED), `limit`(1..200)/`offset`. Returns { org, opportunities:[{ referenceNumber, name, description, closeDate, link, pubDate }] } + honest _meta. HONESTY: the RSS is the COMPLETE set of the org's currently-open opportunities (no server pagination), so totalAvailable = the exact open-opportunity count (never a page length) and this tool pages over it client-side; an empty feed (returned 0) means no open opportunities right now (honest empty, complete:true); `closeDate` is parsed best-effort from the description; a 429/5xx/404/timeout THROWS (never a fake empty); a 200 non-RSS body ⇒ schema_drift; a bad `org` ⇒ invalid_input pre-fetch. Fixed-suffix SSRF (.bonfirehub.com) + redirect:error. Keyless (Bonfire's auth-gated directory API is NOT used)." + " " + STATE_BID_FEEDS_POINTER,
     inputSchema: BonfireSearchOpportunitiesInput,
     handler: (input) => bonfire.searchOpportunities(input),
   }),
@@ -6520,7 +6596,7 @@ export const TOOLS: ToolDef[] = [
   // never-0; standardRate/isOconus are STRING booleans coerced to real booleans.
   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` + `state` (2-letter) OR `zip` (5-digit) — supplying BOTH or NEITHER → invalid_input with 0 fetch; optional `year` (default: current federal fiscal year). Returns { rates:[{ city, county, state, zip, year, isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd is the MAX nightly lodging ceiling for that month — VARIES SEASONALLY (hence a per-month array); mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — genuine 0 preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (unrecognized → null, never fabricated false); months array preserved AS-IS (never padded to 12). API returns COMPLETE rate set (no pagination) → totalAvailable = row count, complete:true. Genuine no-match → honest empty; `errors` field non-null → invalid_input; 429 (DEMO_KEY ~10 req/hr) → rate_limited THROWS; set DATA_GOV_API_KEY (free, api.data.gov/signup) for 1000/hr. 5xx/timeout → upstream_unavailable THROWS; 200 non-JSON → schema_drift. Key rides ONLY in the X-Api-Key header.",
+    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` + `state` (2-letter) OR `zip` (5-digit) — supplying BOTH or NEITHER → invalid_input with 0 fetch; optional `year` (default: current federal fiscal year). Returns { rates:[{ city, county, state, zip, year, fiscalYear (= year, the U.S. FY: Oct 2026 = FY2027), isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd is the MAX nightly lodging ceiling for that month — VARIES SEASONALLY (hence a per-month array); mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — genuine 0 preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (unrecognized → null, never fabricated false); months array preserved AS-IS (never padded to 12). API returns COMPLETE rate set (no pagination) → totalAvailable = row count, complete:true. Genuine no-match → honest empty; `errors` field non-null → invalid_input; 429 (DEMO_KEY ~10 req/hr) → rate_limited THROWS; set DATA_GOV_API_KEY (free, api.data.gov/signup) for 1000/hr. 5xx/timeout → upstream_unavailable THROWS; 200 non-JSON → schema_drift. Key rides ONLY in the X-Api-Key header.",
     inputSchema: GsaPerdiemRatesInput,
     handler: (input) => gsaPerdiem.perdiemRates(input),
   }),
@@ -6567,10 +6643,16 @@ export const TOOLS: ToolDef[] = [
   // (nextCursor extracted from `next`, host re-asserted). type=o FIXED.
   defineTool({
     name: "courtlistener_search_opinions",
-    description: "Search US federal court opinions via CourtListener (www.courtlistener.com/api/rest/v4/search, type=o). ★PROVENANCE: DATA is US federal court PUBLIC RECORDS; the API is CourtListener (Free Law Project, NON-PROFIT) — NOT a .gov API; the .gov primary source (PACER) is PAYWALLED. KEYLESS (optional free COURTLISTENER_API_TOKEN only raises the rate limit). Filters (all optional): `query` (full-text → q), `court` (^[a-z0-9]+$ — e.g. 'uscfc' US Court of Federal Claims, 'cafc' Federal Circuit, 'scotus'), `dateFiledAfter`/`dateFiledBefore` (ISO YYYY-MM-DD), `natureOfSuit` (folded into q — no verified dedicated filter, disclosed in notes), `cursor` (opaque continuation), `order` (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` (total match count) — NOT rows on this page. Pagination is OPAQUE CURSOR (pass _meta.nextCursor back as `cursor`; nextCursor:null/hasMore:false = last page). CourtListener v4 stops counting on deep cursor pages (count:null) → totalAvailable:null DISCLOSED, never faked as results.length. dateFiled is a date STRING; citation → flattened to string/string[]; judge/natureOfSuit/docketNumber null when absent; absoluteUrl is the full CL link. Genuine no-match → honest empty; 400 → invalid_input; 429 → rate_limited (Retry-After honored); 5xx/timeout THROWS; 200 non-JSON/count not number or null → schema_drift; off-host `next` REFUSED (SSRF). Token rides ONLY in the Authorization: Token header.",
+    description: "Search US federal court opinions via CourtListener (www.courtlistener.com/api/rest/v4/search, type=o). ★PROVENANCE: DATA is US federal court PUBLIC RECORDS; the API is CourtListener (Free Law Project, NON-PROFIT) — NOT a .gov API; the .gov primary source (PACER) is PAYWALLED. KEYLESS (optional COURTLISTENER_API_TOKEN only raises the rate limit). Filters (all optional): `party` → caseName:\"…\" FIELDED QUERY — finds actual-party cases (~327 for 'Lockheed Martin'); a bare company name in `query` matches text mentions (~5,954). `query` (free-text → q, AND-ed with caseName when party given). `court` (^[a-z0-9]+$ — e.g. 'uscfc','cafc','scotus'). `dateFiledAfter`/`dateFiledBefore` (ISO). `natureOfSuit` (folded into q — no dedicated filter, disclosed). `cursor`. `order` (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; CURSOR pagination (pass _meta.nextCursor as cursor); count:null on deep pages → totalAvailable:null DISCLOSED. For FCA/qui tam DOCKETS (rarely produce opinions) use courtlistener_search_dockets instead. Token rides ONLY the Authorization header.",
     inputSchema: CourtlistenerSearchOpinionsInput,
     handler: (input) => courtlistener.searchOpinions(input),
   }),
+  defineTool({
+    name: "courtlistener_search_dockets",
+    description: "Search US federal court RECAP DOCKETS via CourtListener (www.courtlistener.com/api/rest/v4/search, type=r). ★USE THIS for FCA / False Claims Act / qui tam matters — these are DOCKETS, not opinions; settlements rarely produce published opinions. ★PROVENANCE: DATA is US federal court PUBLIC RECORDS; the API is CourtListener (Free Law Project, NON-PROFIT) — NOT a .gov API; the .gov primary source (PACER) is PAYWALLED. KEYLESS. Key filters: `party` → caseName:\"…\" FIELDED (actual-party cases, e.g. 'Lockheed Martin' → ~9 FCA dockets). `natureOfSuit` → suitNature:\"…\" REAL DOCKET FIELD (e.g. 'False Claims' to find FCA/qui tam). `query` (free-text AND-ed with caseName when party also given). `court` (^[a-z0-9]+$). `dateFiledAfter`/`dateFiledBefore` (ISO). `cursor`. `order` (default 'dateFiled desc'). Returns { dockets:[{ caseName, caseNameFull, court, courtId, dateFiled, dateTerminated, docketNumber, natureOfSuit, cause, assignedTo, jurisdictionType, url }] } + honest _meta. dateTerminated is null when case still open (NEVER \"\"). url is the full https://www.courtlistener.com/... docket page URL. Docket = case record; outcome/settlement NOT in it — read docket page or DOJ for that. totalAvailable is the API REAL count; CURSOR pagination. Token rides ONLY Authorization header.",
+    inputSchema: CourtlistenerSearchDocketsInput,
+    handler: (input) => courtlistener.searchDockets(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/

package/src/socrata.ts

@@ -204,6 +204,7 @@ export const SOCRATA_DOMAINS = [
   "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)
+  "sharefulton.fultoncountyga.gov", // Fulton County GA (.gov, second portal) — e.g. kp4p-scak (Vendor Payments 226,797 rows 2014–present, updated 2026-09-14, attribution: "Fulton County Government (GA)")
   "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
@@ -245,7 +246,7 @@ const SOCRATA_DOMAIN_SET: ReadonlySet<string> = new Set(SOCRATA_DOMAINS);
  *
  *   data.sfgov.org → data.sf.gov   (confirmed 2026-09-21; all paths 301)
  */
-const MIGRATED_SOCRATA_HOSTS: ReadonlyMap<string, string> = new Map([
+export const MIGRATED_SOCRATA_HOSTS: ReadonlyMap<string, string> = new Map([
   ["data.sfgov.org", "data.sf.gov"],
 ]);
 
@@ -593,6 +594,22 @@ export async function query(args: {
     );
   }
 
+  // ── Response-side aggregate nudge (§A-nudge) ──
+  // When the result is truncated (hasMore) and the caller used no aggregate select,
+  // the agent only sees a PAGE of rows — NOT the total. Nudge toward an aggregate
+  // query so the agent does not try to sum one page manually.
+  if (!isAggregateSelect && hasMore) {
+    // Find the most likely amount-like column from the first row's keys.
+    const firstRow = rows[0];
+    const amountKey =
+      firstRow !== undefined
+        ? (Object.keys(firstRow).find((k) => /amount|amt|total|paid|payment/i.test(k)) ?? "<amount column>")
+        : "<amount column>";
+    notes.push(
+      `This is a PAGE of raw rows (truncated — more rows exist). Do NOT sum this page to get a total. For a grand total: re-query with select='sum(${amountKey})' plus a where filter for vendor/fiscal year. For a top-N ranking: select='vendor_name, sum(${amountKey}) as total' with order='total DESC'. These are aggregate queries — the result is the final answer, not another page.`,
+    );
+  }
+
   return withMeta(
     { domain: args.domain, datasetId: args.datasetId, rows },
     {
@@ -712,6 +729,25 @@ export async function discoverDatasets(args: {
       `Showing ${returned} of ${totalAvailable} matches; raise limit (≤100) or narrow q for the rest.`,
     );
   }
+  // HONESTY (false-zero guard). An empty catalog result is easy to read as "this
+  // portal has no such data", and the per-host note above even calls the index
+  // COMPLETE — but the catalog behaves as if EVERY q term must match, and datasets
+  // rarely repeat their own jurisdiction's name. Measured 2026-09-21 on
+  // data.illinois.gov: q="Illinois state solicitations" -> 0 and
+  // q="Illinois procurement" -> 0, while q="solicitations" -> 1 (6rb8-ntpm). An eval
+  // agent took that zero at face value and told the user no Illinois procurement
+  // datasets exist. So a zero is reported as possibly false, with the fix.
+  if (returned === 0) {
+    // Only "more than one word?" matters here, so test for it directly rather than
+    // splitting: a raw whitespace split is reserved for disclosure tokenizing
+    // (tokenizeForDisclosure, ADR-0022) and this is not a disclosure.
+    const multiWord = /\S\s+\S/.test(args.q);
+    notes.push(
+      multiWord
+        ? `0 matches for a multi-word q — likely a FALSE zero, not proof the data is absent: the catalog behaves as if every term must match, and datasets rarely repeat their jurisdiction's name in their title. Put the place in \`domain\` (not in q) and retry with ONE topical term, e.g. 'solicitations', 'bids', 'contract', 'vendor', 'payments', 'purchase'.`
+        : `0 matches for q=${JSON.stringify(args.q)} — this is not proof the data is absent: publishers title the same thing differently. Retry with a synonym ('solicitations', 'bids', 'contract', 'vendor', 'payments', 'purchase') before concluding the portal has none.`,
+    );
+  }
 
   return withMeta(
     { query: args.q, domain: args.domain ?? null, results },

package/src/toolsets.ts

@@ -195,6 +195,7 @@ export const TOOL_TOOLSET_MAP: Readonly<Record<string, ToolsetName>> = {
   echo_facility_report:        "vetting",
   epa_tri_facilities:          "vetting",
   courtlistener_search_opinions: "vetting",
+  courtlistener_search_dockets: "vetting",
   nonprofit_search:            "vetting",
   nonprofit_financials:        "vetting",
   lda_search_filings:          "vetting",