Skip to main content
Glama

bls-labor-mcp-server

by io.github.cyanheads

Query BLS Dataframes

bls_dataframe_query
Read-onlyIdempotent

Run a single-statement SELECT against the canvas dataframes registered by bls_get_series. 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 — use bls_dataframe_describe to list available dataframes. Supports JOINs, aggregates, window functions, and CTEs. Optional register_as persists the result as a new dataframe with a fresh TTL for chained analysis. Canvas SQL operations consume zero BLS API quota. Requires CANVAS_PROVIDER_TYPE=duckdb.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sqlYesSingle-statement SELECT against df_<id> tables on the shared canvas. Reference dataframes by the names returned in bls_get_series responses or listed by bls_dataframe_describe. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Example: SELECT series_id, year, period, value FROM df_AAAAA_BBBBB WHERE year >= '2020' ORDER BY year DESC.
previewNoInline row preview count. Defaults to row_limit. Set lower (e.g. 50) when chaining via register_as and only a sample is needed immediately.
row_limitNoHard cap on rows materialized in the response (default 1000, max 10000). Full results live on-canvas under register_as when provided.
register_asNoWhen set, persist the query result as a new dataframe under this name. Fresh TTL — not inherited from parent tables. Use to chain analyses without re-running source SQL or consuming additional BLS quota.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe preview or row_limit cap that was applied.
rowsNoMaterialized rows, bounded by preview / row_limit.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of rows returned inline.
noticeNoGuidance when results were capped by preview or row_limit — names which parameter was the binding limiter and suggests how to retrieve the rest. Absent when all rows fit in the response.
columnsNoColumn names in projection order.
row_countNoRows materialized by the query. Exact when register_as is used; otherwise equals row_limit when truncated is true.
truncatedNoTrue when the returned rows were capped.
expires_atNoISO 8601 expiry for the newly registered dataframe, when applicable.
registered_asNoSet when register_as was supplied and the result was materialized.

TDQS

A4.6/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, but the description adds substantial context: the specific rejected operations (writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file functions), denial of system catalogs at the bridge layer, the requirement for CANVAS_PROVIDER_TYPE=duckdb, support for JOINs/aggregates/window functions/CTEs, and the fresh TTL behavior for register_as. This goes well beyond the annotations and gives an agent a clear model of what the tool can and cannot do.

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 multi-sentence but every sentence earns its place: purpose, restrictions, catalog denial, supported features, register_as, quota, and environment. It is front-loaded with the primary purpose and then logically expands. It is slightly dense but well-organized, with no filler. A very minor reduction in length could improve scannability, but it 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 complex SQL query tool with four parameters and an output schema, the description is thorough. It covers how to reference dataframes, what SQL features are supported, security restrictions, the environment requirement, and chaining via register_as. The existence of an output schema covers return format. Nothing critical is missing for an agent to invoke it correctly.

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 coverage is 100%, so each parameter has a description. The description adds extra value: it clarifies that dataframes are referenced as df_<id> tables derived from bls_get_series responses, and that register_as creates a dataframe with a fresh TTL not inherited from parents. It also mentions chaining and quota-free operation. These additions enhance understanding beyond the schema, though the schema already covers the basics.

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: 'Run a single-statement SELECT against the canvas dataframes registered by bls_get_series.' It clearly distinguishes itself from sibling tools by focusing on querying existing dataframes, and it explicitly points to bls_dataframe_describe for listing available dataframes. The read-only scope and supported SQL features are unambiguous.

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?

The description explicitly says to use bls_dataframe_describe to list dataframes, providing an alternative for a different purpose. It also states that Canvas SQL operations consume zero BLS API quota, implying a cost advantage over re-fetching via bls_get_series. It mentions the CANVAS_PROVIDER_TYPE=duckdb prerequisite. It does not explicitly say when not to use this tool versus siblings, but the context is clear enough for an agent to route correctly.

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

All bls-labor-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.6/5.0
Disambiguation5/5

Each tool serves a distinct purpose: searching, listing, fetching, describing, and querying. No overlap between tools like bls_get_latest and bls_get_series, which have clear scope differences.

Naming Consistency5/5

All tools follow the bls_verb_noun pattern in snake_case, e.g., bls_search_series, bls_get_latest, bls_dataframe_query. Consistent and predictable.

Tool Count5/5

Six tools cover the essential workflow: discovery (list, search), retrieval (get_latest, get_series), and analysis (describe, query). Neither too few nor too many.

Completeness4/5

Covers the full read lifecycle from discovery to analysis. Minor gaps like a dedicated metadata tool for specific series, but search_series returns sufficient info. Overall well-scoped.

Resources