Skip to main content
Glama
cliwant

mcp-sam-gov

by cliwant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

open_checkbook_search

Read-only

Search US government checkbook vendor payments by fiscal year, vendor, department, or expense category. Get exact-match results, real totals, and paginated payment rows.

Instructions

Row-level vendor-payment search over a curated US-government Socrata Open Expenditures checkbook portal (keyless) — a SLED spending source. Some govs run Socrata's 'Open Expenditures/Open Checkbook' product, whose public dashboard fronts a keyless app-proxy at {host}/api/checkbook_data.json. First portal: sd = State of South Dakota Open Checkbook (~740,980 vendor-payment rows, ~$8.41B, the ~3 most-recent fiscal years). Inputs: portal (allowlist ENUM — SSRF core), year/vendor/org/expenseCategory (EXACT-match filters), sortBy/sortOrder, limit(1..1000)/offset. Returns { portal, rows:[{vendor, amount, payment_date, org1, expense_category, description, fund, invoice, payment_id}] } + honest _meta. HONESTY: totalAvailable = the API's own count (the REAL filtered total — matches the product's totals.json, e.g. 740,980 unfiltered / 109,887 for org=TRANSPORTATION — NEVER a page length); amount = number|null (a real $0 is 0, an absent value is null, never a fabricated 0); an EXACT-match filter miss ⇒ honest count:0; a deep offset past the end ⇒ returned:0 with the real count preserved; a 429/5xx/timeout THROWS; a non-{data:[],count} body ⇒ schema_drift. ★Only the ~3 most-recent fiscal years are exposed (NOT full history — disclosed). ★The underlying Socrata SODA dataset is login-gated and is NEVER touched — only the public app-proxy the dashboard itself uses. SSRF: fixed allowlist host + assertion + redirect:error.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
orgNoDepartment filter (org1, EXACT match, e.g. 'TRANSPORTATION' → 109,887).
yearNoFiscal-year filter (EXACT match), e.g. '2025'. Default 'All Years' = the exposed ~3-year window (NOT full history).
limitNoRows per page, 1..1000, default 25.
offsetNo0-based offset (snapped to a page×limit boundary; the served offset is disclosed). totalAvailable = the real match count, NOT a page length.
portalYesThe 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).
sortByNoSort field. Pair with sortOrder.
vendorNoVendor name filter (EXACT match, e.g. 'US BANK NA' → 917). A partial/misspelled value returns an honest count:0.
sortOrderNoSort direction (default desc when sortBy is set).
expenseCategoryNoExpense-category filter (EXACT match, e.g. 'CONTRACTUAL SERVICES').

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.16.0
    • changedInput schema / properties / portal / description
      Previous value: -"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)."New value: +"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)."
    • changedInput schema / properties / portal / enum
      Previous value: -[
-  "sd"
-]New value: +[
+  "sd",
+  "ak"
+]
  2. Addedv1.12.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses exhaustive behavior beyond the readOnlyHint and openWorldHint annotations: honest count semantics (totalAvailable is the API's real count, never a page length), exact-match filter behavior returning count:0 on misses, offset past end returning returned:0 with real count preserved, throwing on 429/5xx/timeout, schema_drift detection, SSRF protections (fixed allowlist host + assertion + redirect:error), and data coverage limitations. No contradiction with annotations; the description substantially enriches behavioral understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with the core purpose and immediately clarifies the scope. Every paragraph serves a function: the HONESTY section is dense but critical to correct usage, and the SSRF note is essential. It is verbose, but given the 9 parameters and the nuanced honesty constraints, the length is justified and each sentence earns its place. Slight over-use of formatting stars could be streamlined, but overall structure is effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters, the description fully covers filtering, sorting, pagination, error handling, data source specifics, and honesty guarantees. It even describes the return shape ({ portal, rows[...] }) despite no output schema. The only minor gap is that the exact response for error cases is implied but not explicitly shown, but the description already states 'THROWS' and 'schema_drift', sufficient for an agent to handle failures. This is a complete definition for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds crucial semantics for nearly every parameter: portal enum is expanded with real row counts and fiscal-year specifics, sortBy/sortOrder are paired with behavior, offset is described as 0-based and snapped to page boundaries, and filters are confirmed as EXACT-match. The description goes well beyond the schema's simple field labels, providing operational meaning and examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Row-level vendor-payment search'), a precise resource (curated US-government Socrata Open Expenditures checkbook portal), and the domain (SLED spending). It differentiates from sibling tools by referencing the keyless app-proxy and naming the example portal ('sd' = South Dakota), making it unmistakably distinct from general-purpose data search tools like socrata_query or usas_search_awards.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when this tool is appropriate (when a government runs Socrata's Open Expenditures/Open Checkbook product) and details the two curated portals (sd and ak) with their data scopes. It also states explicit exclusions: only the ~3 most-recent fiscal years are exposed, and the underlying SODA dataset is never touched. This gives clear context for selecting the tool over alternatives and sets expectations about what data will not be returned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools