bls-labor-mcp-server

Describe BLS Dataframes

bls_dataframe_describe

Read-onlyIdempotent

List canvas dataframes materialized by bls_get_series or by bls_dataframe_query register_as, with provenance (source tool, query parameters), TTL, row count, and column schema. Use before writing SQL to confirm column names and types. Lazy-sweeps expired tables before responding. Requires CANVAS_PROVIDER_TYPE=duckdb.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	No	Optional dataframe name to describe a single dataframe — a df_XXXXX_XXXXX name from bls_get_series, or a register_as name from bls_dataframe_query. Omit, or leave blank, to list all active dataframes.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`error`	No	Present when the call failed. Absent on success.
`dataframes`	No	Active dataframes for this tenant, newest first.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedSep 24, 2026

changedInput schema / properties / name / description

Previous value: -"Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all active dataframes."New value: +"Optional dataframe name to describe a single dataframe — a df_XXXXX_XXXXX name from bls_get_series, or a register_as name from bls_dataframe_query. Omit, or leave blank, to list all active dataframes."

changedOutput schema / properties / dataframes / items / properties / column_schema / items / properties / type / description

Previous value: -"DuckDB column type (VARCHAR, BIGINT, DOUBLE, ...)."New value: +"Column type as the canvas reports it: VARCHAR, INTEGER, BIGINT, DOUBLE, BOOLEAN, DATE, TIMESTAMP, JSON, or BLOB. A register_as column of another DuckDB type (DECIMAL, HUGEINT from SUM over integers, SMALLINT, a list) reports VARCHAR, though SQL still sees its real type."

changedOutput schema / properties / dataframes / items / properties / name / description

Previous value: -"Canvas table name (df_XXXXX_XXXXX)."New value: +"Canvas table name — df_XXXXX_XXXXX, or the register_as name given."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: The DataCanvas service is not configured for this deployment. `invalid_dataframe_name`: name is not blank and is not a canvas identifier, so no dataframe can carry it. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "canvas_unavailable"
-]New value: +[
+  "canvas_unavailable",
+  "invalid_dataframe_name"
+]

Changed3 schema fields changedAug 30, 2026

removedOutput schema / properties / dataframes / items / properties / max_rows

Removed value: -{
-  "description": "Materialization cap that produced truncated, when applicable.",
-  "type": "number"
-}

removedOutput schema / properties / dataframes / items / properties / truncated

Removed value: -{
-  "description": "True when the upstream had more rows than were materialized.",
-  "type": "boolean"
-}

changedOutput schema / properties / dataframes / items / required

Previous value: -[
-  "name",
-  "source_tool",
-  "query_params",
-  "created_at",
-  "expires_at",
-  "row_count",
-  "truncated",
-  "column_schema"
-]New value: +[
+  "name",
+  "source_tool",
+  "query_params",
+  "created_at",
+  "expires_at",
+  "row_count",
+  "column_schema"
+]

Changed6 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": [
+      "dataframes"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

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"
+}

removedOutput schema / required
```
Removed value: -[
-  "dataframes"
-]
```

First observedMay 25, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses two extra behavioral traits: 'Lazy-sweeps expired tables before responding' and 'Requires CANVAS_PROVIDER_TYPE=duckdb'. These are valuable side-effect and environment requirements an agent cannot infer from annotations alone, significantly improving transparency.

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?

Three sentences: first sentence states the core function, second gives usage guidance, third discloses side effects and requirements. Information is front-loaded, no filler or redundancy, and every sentence earns its place.

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

Completeness4/5

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

With a rich output schema and a well-documented parameter, the description covers purpose, usage timing, environmental prerequisite, and a side effect. It does not explicitly clarify that it is not for data retrieval, but the usage note about writing SQL implies this. Overall, the description supplies the key operational context an agent needs to choose and invoke the tool correctly.

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

Parameters3/5

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

Input schema already fully documents the single optional 'name' parameter, including examples of valid values (df_XXXXX_XXXXX names, register_as names) and behavior when omitted. The description adds no new parameter-level meaning; with 100% schema coverage, baseline 3 is appropriate.

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 ('List') and resource ('canvas dataframes'), and enumerates the provenance from specific sibling tools (bls_get_series, bls_dataframe_query). It clarifies the tool's metadata-focused role, distinguishing it from query tools like bls_dataframe_query, and lists output fields (TTL, row count, column schema), making the purpose 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?

Explicitly advises 'Use before writing SQL to confirm column names and types,' giving a clear when-to-use context. It does not provide explicit when-not-to-use or alternative routing, but the mention of materialized dataframes and the read-only metadata focus strongly implies this is for inspection, not querying, which is adequate differentiation among siblings.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.