Skip to main content
Glama
cliwant

mcp-sam-gov

by cliwant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

ckan_query

Read-only

Query rows from allowlisted CKAN datastore resources (spend, procurement, vendor tables) by resource ID, with full-text search, filters, sort, and pagination.

Instructions

Query rows from an allowlisted CKAN datastore resource (keyless; state/city spend/checkbook/procurement/vendor tables on the CKAN Action API). VA eVA PO lines: host=data.virginia.gov resourceId=3c7f1bde-35b0-4fbf-b89c-978a19124d53. Full map: read resource samgov://data-map/state-local. Input host (curated allowlist enum — the SSRF host guard: data.ca.gov, data.virginia.gov, data.boston.gov), resourceId (36-char lowercase UUID, from ckan_discover_datasets), optional q (full-text), filters (constrained object {field:value} we JSON.stringify), sort, limit (≤1000, def 100), offset. HONESTY: CKAN's envelope carries a real result.total — the DEFAULT is an EXACT total (exact totalAvailable + hasMore); the rare estimated total (total_was_estimated:true) is disclosed via totalIsEstimated + a note and does NOT drive pagination (it can be above OR below the truth). Genuine-empty ⇒ complete:true/total:0; an outage/404/409 or success:false THROWS (never a fake empty). Values are typed per result.fields[].type.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoOptional full-text search across the record (CKAN `q`).
hostYesWhich allowlisted CKAN portal to query (curated .gov hosts — the SSRF host allowlist, no free host): data.ca.gov (CA), data.virginia.gov (VA — eVA), data.boston.gov (City of Boston Checkbook).
sortNoOptional sort, e.g. '_id asc' or 'amount desc'. A bad field ⇒ 409 ⇒ invalid_input.
limitNoRows per page, 1..1000, default 100.
offsetNo0-based row offset for pagination, default 0.
filtersNoOptional structured field filters, e.g. {"Fiscal Year":"2013-2014"}. A constrained object (string/number/array values only) that we JSON.stringify; a bad field ⇒ upstream HTTP 409 ⇒ invalid_input (surfaced, never silent).
resourceIdYesThe datastore resource_id, a 36-char lowercase UUID e.g. 'bb82edc5-9c78-44e2-8947-68ece26197c5' (from ckan_discover_datasets, a datastoreActive:true resource).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.16.0
    • changedInput schema / properties / host / enum
      Previous value: -[
-  "data.ca.gov",
-  "data.virginia.gov",
-  "data.boston.gov"
-]New value: +[
+  "data.ca.gov",
+  "data.ok.gov",
+  "data.virginia.gov",
+  "data.boston.gov"
+]
  2. Addedv1.12.0

TDQS

A4.8/5.0
Behavior5/5

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

The description goes far beyond the readOnlyHint/openWorldHint annotations: it discloses keyless access, the SSRF host allowlist, exact vs estimated result totals, totalIsEstimated behavior, and that errors/outages throw rather than returning fake empty results. It also notes typed values per result.fields[].type, which is essential behavioral context.

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

Conciseness5/5

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

The description is dense but well-structured: purpose first, then concrete examples, parameter inventory, and a clearly marked HONESTY section for edge-case behavior. Every sentence contributes either scoping, parameter semantics, or error/total semantics.

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 query tool with no output schema, the description explains return values, total semantics, pagination implications, error behavior, and parameter constraints. An agent has everything needed to invoke it correctly and interpret the response.

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?

With 100% schema coverage, the baseline is 3, but the description adds substantial meaning: filters are JSON.stringified, bad fields surface as 409 invalid_input, resourceId must be a 36-char lowercase UUID sourced from ckan_discover_datasets, and limit defaults/upper bound are restated. This goes well beyond the schema's individual field descriptions.

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 opens with a specific verb and resource: 'Query rows from an allowlisted CKAN datastore resource', and scopes it to the CKAN Action API with concrete examples (VA eVA PO lines and host/resourceId). This makes it clearly distinguishable from sibling tools like socrata_query and ckan_discover_datasets.

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

Usage Guidelines4/5

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

It provides clear context: this is for allowlisted CKAN datastore resources, and the resourceId comes from ckan_discover_datasets. It does not explicitly state when-not-to-use alternatives like socrata_query, but the CKAN-specific framing and workflow hint are enough for an agent to select it appropriately.

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