bls-labor-mcp-server

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

Name	Required	Description
`sql`	Yes	Single-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.
`preview`	No	Inline 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_limit`	No	Hard cap on rows materialized in the response (default 1000, max 10000). Full results live on-canvas under register_as when provided.
`register_as`	No	When 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

Name	Required	Description
`cap`	No	The preview or row_limit cap that was applied.
`rows`	No	Materialized rows, bounded by preview / row_limit.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of rows returned inline.
`notice`	No	Guidance 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.
`columns`	No	Column names in projection order.
`row_count`	No	Rows materialized by the query. Exact when register_as is used; otherwise equals row_limit when truncated is true.
`truncated`	No	True when the returned rows were capped.
`expires_at`	No	ISO 8601 expiry for the newly registered dataframe, when applicable.
`registered_as`	No	Set when register_as was supplied and the result was materialized.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed10 schema fields changedAug 24, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "columns",
+      "row_count",
+      "rows"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / cap

Added value: +{
+  "description": "The preview or row_limit cap that was applied.",
+  "type": "number"
+}

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: The DataCanvas service is not configured for this deployment. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / row_count / description

Previous value: -"Total rows the query produced (may exceed rows.length when capped by row_limit)."New value: +"Rows materialized by the query. Exact when register_as is used; otherwise equals row_limit when truncated is true."

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of rows returned inline.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the returned rows were capped.",
+  "type": "boolean"
+}

removedOutput schema / required

Removed value: -[
-  "columns",
-  "row_count",
-  "rows"
-]

Changed1 schema field changedJun 8, 2026

changedOutput schema / properties / notice / description

Previous value: -"Guidance when results were capped by row_limit — e.g. to use register_as to persist all rows or increase row_limit. Absent when all rows fit in the response."New value: +"Guidance 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."

Changed1 schema field changedMay 30, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when results were capped by row_limit — e.g. to use register_as to persist all rows or increase row_limit. Absent when all rows fit in the response.",
+  "type": "string"
+}

First observedMay 25, 2026

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 tools Inspect

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.

Query BLS Dataframes

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

TDQS

Resources