@cliwant/mcp-sam-gov 1.15.0 → 1.16.0

package/src/pricing.ts

@@ -164,10 +164,26 @@ function epochToIso(v: number | string | undefined): string | null {
   return null;
 }
 
+// Maximum pages to scan when a client-side filter (county / constructionType)
+// requires a full-state sweep.  10 pages × 50 rows = 500 WDs — well above any
+// real state's active DBA stock (IL has 70 as of 2026-09-22).
+const WD_SCAN_PAGE_CAP = 10;
+const WD_SCAN_SIZE = 50; // max the SGS API accepts per request
+
+/** Extract constructionTypes as a lowercase string array (handles string[] or unknown). */
+function resultConstructionTypes(r: SgsResult): string[] {
+  const ct = r.constructionTypes;
+  if (!ct) return [];
+  if (Array.isArray(ct)) return ct.map((v) => String(v).toLowerCase());
+  if (typeof ct === "string") return [ct.toLowerCase()];
+  return [];
+}
+
 export async function searchWageDeterminations(args: {
   coverage: string;
   state?: string;
   county?: string;
+  constructionType?: string;
   query?: string;
   activeOnly?: boolean;
   standardOnly?: boolean;
@@ -181,35 +197,47 @@ export async function searchWageDeterminations(args: {
   const page = Math.max(0, Math.floor(args.page ?? 0));
   const stateFilter = args.state?.trim().toUpperCase() || undefined;
   const countyFilter = args.county?.trim().toLowerCase() || undefined;
+  const ctFilter = args.constructionType?.trim().toLowerCase() || undefined;
+
+  // When county or constructionType is given, we must scan ALL pages for the
+  // state to avoid missing matching WDs (e.g. IL has 70 DBA WDs — the target
+  // Cook County Building WD is on page 1).  We use max size=50 per fetch and
+  // cap at WD_SCAN_PAGE_CAP pages to keep the request count bounded.
+  const needsFullScan = Boolean(countyFilter || ctFilter);
 
-  const params = new URLSearchParams({
-    index,
-    size: String(limit),
-    page: String(page),
-    mode: "search",
-    sort: "-modifiedDate",
-  });
-  if (activeOnly) params.set("is_active", "true");
-  if (standardOnly) params.set("is_standard", "true");
-  // `q` matches WD number/title ONLY (NOT occupation) — verified q=guard→0.
-  if (args.query) params.set("q", args.query);
-  // `state` IS honored server-side (LIVE-VERIFIED 2026-07-03: index=sca&state=VA
-  // → 30 vs 1028 unfiltered, and every returned WD's location contains VA;
-  // state=ZZ → 0). It wants the 2-letter USPS code (a full name like "Virginia"
-  // → 0). This CORRECTS the earlier brief which assumed state was ignored.
   const filtersApplied: string[] = [`coverage(${index})`];
   const filtersDropped: string[] = [];
   const notes: string[] = [];
   if (activeOnly) filtersApplied.push("activeOnly");
   if (standardOnly) filtersApplied.push("standardOnly");
   if (args.query) filtersApplied.push("query(WD number/title only)");
+
+  // Build the base URLSearchParams that are shared across every page fetch.
+  function buildParams(pg: number, sz: number): URLSearchParams {
+    const p = new URLSearchParams({
+      index,
+      size: String(sz),
+      page: String(pg),
+      mode: "search",
+      sort: "-modifiedDate",
+    });
+    if (activeOnly) p.set("is_active", "true");
+    if (standardOnly) p.set("is_standard", "true");
+    // `q` matches WD number/title ONLY (NOT occupation) — verified q=guard→0.
+    if (args.query) p.set("q", args.query);
+    return p;
+  }
+
+  // `state` IS honored server-side (LIVE-VERIFIED 2026-07-03: index=sca&state=VA
+  // → 30 vs 1028 unfiltered, and every returned WD's location contains VA;
+  // state=ZZ → 0). It wants the 2-letter USPS code (a full name like "Virginia"
+  // → 0). This CORRECTS the earlier brief which assumed state was ignored.
+  const needsClientState =
+    stateFilter !== undefined && !/^[A-Z]{2}$/.test(stateFilter);
   if (stateFilter) {
-    if (/^[A-Z]{2}$/.test(stateFilter)) {
-      params.set("state", stateFilter);
+    if (!needsClientState) {
       filtersApplied.push("state(server-side)");
     } else {
-      // Not a 2-letter code → the server would return 0; apply client-side
-      // instead so a full name still works, and disclose it.
       filtersDropped.push("state(server-side; not a 2-letter code)");
       notes.push(
         `The state value '${args.state}' is not a 2-letter USPS code; the SGS 'state' param only matches 2-letter codes (a full name returns 0), so it was applied CLIENT-SIDE over the fetched page instead. Pass a 2-letter code (e.g. 'VA') for a precise server-side filter.`,
@@ -217,30 +245,75 @@ export async function searchWageDeterminations(args: {
     }
   }
 
-  const url = `${SGS_BASE}?${params.toString()}`;
-  const json = await getJson<SgsSearchResp>(url, SAM_HAL_HEADERS, `sam:sgs:${index}`);
-  const rawResults = json._embedded?.results ?? [];
-  const serverTotal = json.page?.totalElements ?? null;
+  // ── Fetch: one page (no client filters) OR full-state scan ──────
+  let allRaw: SgsResult[];
+  let serverTotal: number | null;
+  let scanCapHit = false;
+
+  if (!needsFullScan) {
+    // Original single-page path (no county/constructionType filter).
+    const params = buildParams(page, limit);
+    if (!needsClientState && stateFilter) params.set("state", stateFilter);
+    const url = `${SGS_BASE}?${params.toString()}`;
+    const json = await getJson<SgsSearchResp>(url, SAM_HAL_HEADERS, `sam:sgs:${index}`);
+    allRaw = json._embedded?.results ?? [];
+    serverTotal = json.page?.totalElements ?? null;
+  } else {
+    // Full-state scan: fetch all pages with size=50 until exhausted or cap.
+    const scanParams = buildParams(0, WD_SCAN_SIZE);
+    if (!needsClientState && stateFilter) scanParams.set("state", stateFilter);
+    const firstUrl = `${SGS_BASE}?${scanParams.toString()}`;
+    const firstJson = await getJson<SgsSearchResp>(firstUrl, SAM_HAL_HEADERS, `sam:sgs:${index}`);
+    allRaw = firstJson._embedded?.results ?? [];
+    serverTotal = firstJson.page?.totalElements ?? null;
+    const totalPages = firstJson.page?.totalPages ?? 1;
+
+    const pagesToFetch = Math.min(totalPages, WD_SCAN_PAGE_CAP);
+    if (totalPages > WD_SCAN_PAGE_CAP) scanCapHit = true;
+
+    for (let pg = 1; pg < pagesToFetch; pg++) {
+      const p = buildParams(pg, WD_SCAN_SIZE);
+      if (!needsClientState && stateFilter) p.set("state", stateFilter);
+      const pgJson = await getJson<SgsSearchResp>(
+        `${SGS_BASE}?${p.toString()}`,
+        SAM_HAL_HEADERS,
+        `sam:sgs:${index}`,
+      );
+      allRaw = allRaw.concat(pgJson._embedded?.results ?? []);
+    }
+  }
 
-  // Client-side filtering: county is NOT a documented SGS server param, so it
-  // is applied here over the fetched page. A non-2-letter state also lands here.
-  const needsClientState = filtersDropped.some((f) => f.startsWith("state"));
-  let filtered = rawResults;
+  // ── Client-side filtering ────────────────────────────────────────
+  let filtered = allRaw;
   if (needsClientState && stateFilter) {
     filtered = filtered.filter((r) =>
-      resultStateCodes(r).some((c) => c === stateFilter || r.location?.state?.name?.toUpperCase() === stateFilter),
+      resultStateCodes(r).some(
+        (c) => c === stateFilter || r.location?.state?.name?.toUpperCase() === stateFilter,
+      ),
     );
   }
   if (countyFilter) {
-    filtersApplied.push("county(client-side)");
+    filtersApplied.push("county(client-side, full-state scan)");
     filtered = filtered.filter((r) =>
       resultCounties(r).some((c) => c.name.toLowerCase().includes(countyFilter)),
     );
-    notes.push(
-      "County is filtered CLIENT-SIDE over the fetched page only (the SGS API has no county filter). A county filter combined with a small limit can miss WDs on later pages — raise `limit` or narrow by `state` (server-side) to be sure.",
+  }
+  if (ctFilter) {
+    filtersApplied.push(`constructionType(client-side, value=${args.constructionType})`);
+    filtered = filtered.filter((r) =>
+      resultConstructionTypes(r).includes(ctFilter),
     );
   }
 
+  // ── Specificity ranking: single-county WDs before multi-county ──
+  if (countyFilter) {
+    filtered.sort((a, b) => {
+      const aCount = resultCounties(a).length;
+      const bCount = resultCounties(b).length;
+      return aCount - bCount; // 1-county first, then 2-county, etc.
+    });
+  }
+
   const determinations = filtered.map((r) => {
     const coverageCode = r.type?.code ?? (index === "sca" ? "SCA" : "DBA");
     return {
@@ -273,27 +346,48 @@ export async function searchWageDeterminations(args: {
     "The `q` parameter matches the WD number/title only — it does NOT search by occupation or job title (e.g. q=guard returns 0). To find rates for a specific occupation, open the WD and read its rate table.",
   );
 
-  // totalAvailable: the server total is REAL for the coverage/active/standard/
-  // query/state filters (state is server-side). But when we additionally filter
-  // client-side (county, or a non-code state), the returned page count no longer
-  // reflects a full server total for THAT combined filter → null it out and say so.
-  const clientFiltered = Boolean(countyFilter) || needsClientState;
-  const totalAvailable = clientFiltered ? null : serverTotal;
+  // ── Honest meta ──────────────────────────────────────────────────
+  const clientFiltered = Boolean(countyFilter) || Boolean(ctFilter) || needsClientState;
+  const scannedCount = allRaw.length;
   const returned = determinations.length;
-  const truncated = clientFiltered
-    ? true // page-bounded client filter → can't prove completeness
-    : serverTotal !== null && page * limit + returned < serverTotal;
 
-  if (clientFiltered) {
+  // When we did a full-state scan, totalAvailable is the REAL count of matching
+  // WDs across the scanned pages (not null).  Only null it when the scan cap was
+  // hit (we didn't see all pages) or when there was no client filter.
+  let totalAvailable: number | null;
+  let truncated: boolean;
+
+  if (!clientFiltered) {
+    // No client filter: server total is accurate for this result set.
+    totalAvailable = serverTotal;
+    truncated = serverTotal !== null && page * limit + returned < serverTotal;
+  } else if (needsFullScan && !scanCapHit) {
+    // Full scan completed: real match count is known.
+    totalAvailable = returned;
+    truncated = false;
+  } else {
+    // Scan cap hit or no full scan (shouldn't happen but be safe).
+    totalAvailable = null;
+    truncated = true;
+  }
+
+  if (needsFullScan) {
+    const stateLabel = stateFilter ?? "all states";
+    const capNote = scanCapHit
+      ? ` (scan cap of ${WD_SCAN_PAGE_CAP * WD_SCAN_SIZE} WDs reached — some WDs may have been missed)`
+      : "";
     notes.push(
-      "totalAvailable is null because a client-side filter (county and/or a non-code state) was applied over just the fetched page — the true match count for the combined filter is unknown. The server-side total for the coverage/state/active filters was " +
-        (serverTotal ?? "unknown") +
-        ".",
+      `Scanned ${scannedCount} of ${serverTotal ?? scannedCount} ${stateLabel} ${index.toUpperCase()} WDs across all pages${capNote}. ` +
+        (countyFilter ? `County filter applied across all scanned WDs. ` : "") +
+        (ctFilter ? `constructionType filter (${args.constructionType}) applied. ` : "") +
+        (countyFilter
+          ? "Single-county WDs ranked first — they are almost always the most specific match for a given locality. "
+          : ""),
     );
   }
 
   return withMeta(
-    { determinations, coverageIndex: index, page, limit },
+    { determinations, coverageIndex: index, page: needsFullScan ? 0 : page, limit: needsFullScan ? returned : limit },
     {
       source: WD_SEARCH_SOURCE,
       keylessMode: true,
@@ -301,9 +395,9 @@ export async function searchWageDeterminations(args: {
       totalAvailable,
       truncated,
       pagination: {
-        offset: page * limit,
-        limit,
-        nextOffset: truncated ? (page + 1) * limit : null,
+        offset: 0,
+        limit: needsFullScan ? returned : limit,
+        nextOffset: truncated && !needsFullScan ? (page + 1) * limit : null,
         hasMore: truncated,
       },
       filtersApplied,

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.16.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(
@@ -5639,7 +5663,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 +5867,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 +6226,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 +6544,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),
   }),

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 },