Skip to main content
Glama

treasury-fiscaldata-mcp-server

by io.github.cyanheads

Query Treasury Dataframes

treasury_dataframe_query
Read-onlyIdempotent

Run a single-statement SELECT against DataCanvas dataframes registered by treasury_query_dataset, treasury_get_debt, treasury_get_interest_rates, and treasury_get_exchange_rates. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer. All Treasury dataframe columns are VARCHAR — CAST to DECIMAL or DATE for arithmetic and date comparisons. Use treasury_dataframe_describe to list available table names and column schemas before querying.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sqlYesSingle-statement SELECT against df_<id> tables. All values in Treasury dataframes are VARCHAR (strings) per the API contract — CAST to DECIMAL or DATE for arithmetic and date comparisons. Example: SELECT record_date, CAST(tot_pub_debt_out_amt AS DECIMAL) AS debt FROM df_xxxxx ORDER BY record_date DESC LIMIT 10.
previewNoRows in the immediate response. Defaults to row_limit and may not exceed it. Set lower when using register_as.
row_limitNoHard cap on rows the query may produce. Default 1000, max 10000. A query matching more rows than this stops at the cap and row_count_capped comes back true — raise it, or use register_as to materialize the whole result.
register_asNoPersist the result as a new dataframe under this exact name, to chain analyses. The name is used verbatim — any name works, and a df_ prefix keeps it consistent with the tables the data tools mint. Echoed back in registered_as.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe row cap that was applied — preview when supplied, otherwise row_limit.
rowsNoMaterialized rows, bounded by preview / row_limit.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of rows returned in this response.
noticeNoGuidance when the query returned no rows, or when results were capped by preview or row_limit.
columnsNoColumn names in projection order.
row_countNoRows the query produced, up to row_limit. Exceeds rows.length when preview returned fewer. Read with row_count_capped: when that is true this number is row_limit itself, and the size of the full result is not in this response.
truncatedNoTrue when the returned rows were capped below the full result set.
expires_atNoISO 8601 expiry timestamp for the newly registered dataframe, when applicable.
registered_asNoSet when register_as was supplied and the new dataframe was materialized.
row_count_cappedNoTrue when the query matched more rows than row_limit, so row_count is that cap rather than a total. False means row_count is exact — including when it happens to equal row_limit.

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description goes further by revealing that all columns are VARCHAR (requiring CAST), that system catalogs are denied at the bridge layer, and that row_count_capped can be true when exceeding row_limit. This adds behavioral context beyond the annotations, such as the VARCHAR contract and query cap behavior, making the tool's execution semantics clear.

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 three sentences, each carrying weight: the first defines the action and scope, the second lists restrictions, and the third gives typing guidance and recommends the describe tool. It is front-loaded with the core purpose, then constraints, then usage tip. No filler; every sentence earns its place. This is optimally concise for the information conveyed.

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?

Given the tool's complexity (SQL execution with restrictions, multiple parameters, and a need for schema discovery), the description covers all essential aspects: what it does, safety constraints, VARCHAR caveat, how to discover available tables, and real-world usage via an example. The output schema exists, so return values are documented elsewhere. The description leaves no critical gaps for an agent to call the tool correctly and interpret results (e.g., casting, row caps).

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds value by reinforcing the VARCHAR casting requirement and providing an example SQL statement that demonstrates the CAST pattern. While the description repeats some schema details (e.g., row_limit cap), it enhances understanding of how parameters interact (preview vs. row_limit vs. register_as) and offers a concrete usage example. This is above the baseline of 3 because it adds context that helps avoid misuse.

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 clearly identifies the tool's action: 'Run a single-statement SELECT against DataCanvas dataframes'. It names the specific registration tools (treasury_query_dataset, treasury_get_debt, etc.) and explicitly distinguishes from treasury_dataframe_describe by telling users to call that tool for table listing. The read-only constraint and denial of DDL/DROP/etc. further pin down the scope, leaving no ambiguity about what this tool does and what it is not.

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 provides explicit usage direction: 'Use treasury_dataframe_describe to list available table names and column schemas before querying.' It also explains when to avoid the tool (writes/DDL are rejected) and gives practical tips like casting VARCHAR to DECIMAL/DATE for arithmetic and date comparisons. This is clear, actionable guidance that helps an agent decide when to use this tool and how to use it correctly.

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

All treasury-fiscaldata-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0
Disambiguation4/5

The tools are mostly distinct: each specialized getter (debt, exchange rates, interest rates) targets a specific dataset, while the generic query tool and list tool serve discovery and ad-hoc queries. There is some overlap between the generic treasury_query_dataset and the specialized getters, but the descriptions clearly differentiate their intended use (specialized modes vs. raw endpoint queries).

Naming Consistency5/5

All tools follow a consistent treasury_verb_noun pattern with snake_case (e.g., treasury_get_debt, treasury_list_datasets, treasury_dataframe_query). The verbs (get, list, query, describe) are consistent in style and each noun is plural or singular appropriately, making the naming uniform and predictable.

Tool Count5/5

With 7 tools, the server is well-scoped for its purpose of accessing Treasury fiscal data. It offers dedicated tools for common datasets, a generic query tool for flexibility, and DataFrame staging/query utilities, with no redundancy or overwhelming number of tools.

Completeness5/5

The tool surface covers essential workflows: discovering available datasets (list_datasets), querying any endpoint (query_dataset), retrieving common datasets with convenience modes (debt, exchange rates, interest rates), and handling large result sets via DataCanvas staging (describe/query). No obvious gaps exist; even less common datasets are accessible through the generic query tool.

Resources