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.

Input 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

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.

Changed1 schema field changedNov 1, 2026

changedOutput schema / properties / dataframes / items / properties / expires_at / description

Previous value: -"ISO 8601 expiry timestamp (sliding TTL)."New value: +"ISO 8601 table expiry fixed at creation; reads do not extend it."

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.3/5.0

Behavior4/5

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

Annotations already cover read-only and idempotency, but the description adds real behavioral context: returned provenance, TTL, row counts, column schema, and the non-obvious side effect that expired tables are lazy-swept before responding. That sweep behavior is exactly the kind of trait an agent could not infer from structured fields.

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, front-loaded with the verb and resource, then the usage trigger, then the side effect. Nothing is redundant with the tool name or title.

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?

Covers what is listed, where entries come from, what metadata accompanies each entry, when to call it, and a latent side effect — more than enough for a one-optional-parameter read tool, especially with an output schema carrying return structure.

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?

Schema coverage is 100% and the single `name` parameter is already fully documented in the schema, including the omit-to-list-all case. The description reinforces 'list all' semantics but adds no format or edge-case detail beyond it, so the baseline 3 applies.

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?

States a specific verb and resource ("List canvas dataframes") and pins down provenance by naming the exact sibling tools that materialize them (bls_get_series, bls_dataframe_query register_as). An agent can immediately tell this apart from the sibling query/series tools.

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?

"Use before writing SQL to confirm column names and types" gives a clear selection context. It stops short of an explicit exclusion (e.g., 'use bls_dataframe_query instead if you already know the columns'), so the alternative is implied rather than stated.

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.