From bf85e583d3f3a81ca66ef6f0bd2f0056c9df026e Mon Sep 17 00:00:00 2001 From: stxkxs <139715017+stxkxs@users.noreply.github.com> Date: Tue, 18 Aug 2026 23:40:21 -0700 Subject: [PATCH] profile: publish the tool index and source the data claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The org profile claimed "agent-native tools" and "one MCP server" while offering an agent nothing but prose — no tool names, no contracts, no way in. It also asserted "217M+ itemized contribution records" and "refreshed nightly" with no locator and no date, on a page whose stated promise is that nothing is asserted without a locator you can re-fetch. ────────────────────── The tool index ────────────────────── Adds all fourteen live tools in two families, with the actor catalog beneath. Contracts are the tool descriptions exactly as registered in the MCP server, so an agent reading this page and an agent reading the server see the same text rather than two drifting paraphrases. The actor table is separate from the tool table on purpose: the mapping is not one-to-one. Fourteen tools ship across seven query actors plus the MCP server, and `opportunity_search` alone spans SAM.gov and Grants.gov. A one-row-per-actor table would have implied one tool each. All eight actor URLs verified to resolve before publishing. The MCP connection host is deliberately absent. citature-mcp runs as an Apify Standby actor, so its host is assigned by the platform at start and exists in the console rather than anywhere quotable. The page says so and points at the listing instead. On a surface whose premise is that every claim carries a locator, a plausible-looking endpoint would have been the worst available defect — the page states the gap rather than filling it. ──────────────────────── The claims ──────────────────────── "217M+ across the 2020–2026 cycles" is kept, because it was checked and it holds: 217,588,079 rows in the conformed contribution table, 217,574,406 of them inside those cycles. The "+" makes it a floor, which only grows. "Refreshed nightly" was ambiguous rather than false, and the ambiguity is what made it dangerous here. The pipeline does run nightly against all four sources; the FEC data is not new nightly, because FEC publishes bulk files on the two-year election cycle and the ingest correctly reports "caught up to horizon" in between. A reader pairing the old sentence with a five-week-old FEC watermark would reasonably conclude something was broken. Cadence is now stated per source, which is both true and a stronger claim, since it shows the upstream is modelled rather than assumed. No as-of date is printed, and that is the deliberate choice rather than an omission. A date typed into markdown is a promise with a shelf life and becomes the next stale claim the moment nobody regenerates it. The real receipt is per-answer: every answer already carries `retrieved_at` next to the source's own `as_of`, and the page now says so. ───────────────────────── The rules ───────────────────────── "The rules" now quotes the guardrail literals verbatim instead of paraphrasing them. Those strings are single-sourced in the core package and ship in every receipt envelope and every tool description; the profile had drifted into its own wording, which is the same fork this change fixes everywhere else. Note for the storefront: the same 217M sentence is hand-written in the actor catalog and therefore live in the Apify listings too. That surface is not this repository's to edit. Co-authored-by: stxkxsbot <275011021+stxkxsbot@users.noreply.github.com> --- profile/README.md | 96 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 79 insertions(+), 17 deletions(-) diff --git a/profile/README.md b/profile/README.md index 520a40b..88f8448 100644 --- a/profile/README.md +++ b/profile/README.md @@ -33,31 +33,93 @@ can re-fetch yourself. ## The data -Primary sources only. Public-domain US federal records, refreshed nightly from -the source of record — never an aggregator. +Primary sources only. Public-domain US federal records, ingested nightly from the +source of record — never an aggregator. What each nightly run *finds* depends on +the upstream's own cadence, so coverage is stated per source rather than as one +number: - **FEC** — campaign finance: 217M+ itemized contribution records across the - 2020–2026 cycles, plus committees and candidates -- **USASpending** — federal awards and contracts, keyed on recipient UEI -- **SAM.gov** — contract opportunities and solicitations -- **Grants.gov** — grant opportunities + 2020–2026 cycles, plus committees and candidates. FEC publishes bulk files on + the two-year election cycle, so the ingest advances when new files land rather + than daily. +- **USASpending** — federal awards and contracts, keyed on recipient UEI. New + records land daily. +- **SAM.gov** — contract opportunities and solicitations. New records land daily. +- **Grants.gov** — grant opportunities. Advances when the upstream publishes. + +No date is printed here on purpose. Every answer carries its own `retrieved_at` +(when citature fetched the record) alongside the source's own `as_of` date, which +is a separate field — a receipt on the answer beats an as-of line on a page that +nobody regenerates. ## The tools -Delivered on the [Apify Store](https://apify.com/citature). - -- **Money** — FEC contributions by state and committee type, federal awards by - agency/state/recipient, follow-the-money committee inflows, and funding-entity - lookup and search -- **GovCon** — expiring-contract recompetes by NAICS with incumbent UEI, - contractor award lineage by agency, and agency buying patterns by year -- **MCP** — every tool above delivered as agent-native calls from one MCP server +Fourteen tools in two families, all live. Each is callable from the MCP server or +as a standalone [Apify actor](https://apify.com/citature). The mapping is not +one-to-one — several tools share an actor, and `opportunity_search` spans both +SAM.gov and Grants.gov. + +Descriptions below are the tool descriptions as registered, so an agent reading +this page and an agent reading the server see the same contract. + +### Money + +| Tool | Contract | +| --- | --- | +| `contributions_by_state` | Individual FEC contribution dollars for an election cycle, totaled by the contributor's state of origin, largest first. | +| `contributions_by_committee_type` | Individual FEC contribution dollars for an election cycle, totaled by the recipient committee's type, largest first. | +| `awards_by_agency` | Federal contract-award dollars for a fiscal year, ranked by the awarding agency. Declares the exact agency crosswalk in the receipt. | +| `awards_by_state` | Federal contract-award dollars for a fiscal year, ranked by place-of-performance state (a native award field, no join). | +| `awards_by_recipient` | Federal contract-award dollars for a fiscal year, ranked by recipient keyed on the universal federal awardee UEI. Declares the UEI crosswalk. | +| `follow_the_money` | Itemized contribution dollars flowing into an FEC committee, aggregated by the contributor's state of origin. Entity-level only; declares the committee-id crosswalk. | +| `committee_lookup` | Look up one FEC committee by its committee id. Returns the committee or a null answer with a citation when none is found. | +| `candidate_lookup` | Look up one FEC candidate by its candidate id. Returns the candidate or a null answer with a citation when none is found. | +| `committee_search` | Prefix-search FEC committees by name (case-insensitive, bounded). Each result carries the citature entity id next to the FEC id. | +| `candidate_search` | Prefix-search FEC candidates by name (case-insensitive, bounded). Each result carries the citature entity id next to the FEC id. | + +### GovCon + +| Tool | Contract | +| --- | --- | +| `recompetes_expiring` | Federal contracts whose period of performance ends within a YYYY-MM month window, soonest first, each with the incumbent (by UEI) and its obligation. Optional NAICS (prefix) and awarding-agency (name) filters. Declares the exact UEI and agency-code crosswalks. | +| `incumbent_history` | A federal contractor's contract lineage per agency and NAICS, by exact UEI or recipient-name prefix (at least one required): contract count, total obligated, fiscal-year span, latest period-of-performance end. Declares the exact UEI and agency-code crosswalks. | +| `agency_buying` | Federal contract obligations, contract counts, and distinct-contractor counts by awarding agency, NAICS, and fiscal year. All filters optional. Declares the exact agency-code crosswalk and the UEI behind the distinct-contractor count. | +| `opportunity_search` | Open and forecasted procurement opportunities across SAM.gov and Grants.gov, newest first, filterable by NAICS, agency, posted-date window, and active state. Single-source native records, so no cross-source join; cites each contributing source. | + +### Actors + +| Actor | Family | +| --- | --- | +| [`funding-entity-lookup`](https://apify.com/citature/funding-entity-lookup) | money | +| [`fec-contributions`](https://apify.com/citature/fec-contributions) | money | +| [`federal-awards`](https://apify.com/citature/federal-awards) | money | +| [`follow-the-money`](https://apify.com/citature/follow-the-money) | money | +| [`govcon-recompetes`](https://apify.com/citature/govcon-recompetes) | govcon | +| [`incumbent-history`](https://apify.com/citature/incumbent-history) | govcon | +| [`agency-buying-patterns`](https://apify.com/citature/agency-buying-patterns) | govcon | +| [`citature-mcp`](https://apify.com/citature/citature-mcp) | mcp | + +Every tool above is delivered as agent-native calls from one MCP server, +published as the [`citature-mcp`](https://apify.com/citature/citature-mcp) actor +and served over Streamable HTTP on the `/mcp` path. + +The connection host is assigned by the Apify platform when the actor starts in +Standby mode, so it is not a fixed address this page can quote — take it from the +actor's listing. Nothing here states an endpoint it cannot cite. ## The rules -Research over public records — never legal, financial, or eligibility advice. -Entity-level data only; no individual-person products. citature reports what the -record says and never renders a verdict. +The standing caveats, quoted from the literals every receipt and every tool +description ships: + +- Research over public-domain federal records — not legal, financial, or + eligibility advice. +- citature reports what the record says. It never renders a compliance verdict, + a screening pass/fail, or a recommendation. +- Entity-level records only (committees, candidates, recipients, agencies, + contracts). No individual-person data. + +Money is integer cents. ---