bls-labor-mcp-server

List BLS Surveys

bls_list_surveys

Read-onlyIdempotent

List BLS survey programs with their abbreviation codes, full names, and metadata about calculation support and annual averages. Use to discover which survey covers a topic before calling bls_search_series; each row's searchCoverage says whether bls_search_series reaches the survey through its offline index, composes its SeriesIDs from code tables, or cannot search it, in which case its series are fetched by SeriesID with bls_get_series. Optional category filter narrows results to prices, employment, wages, productivity, injuries, or time_use surveys.

Input Schema

Name	Required	Description	Default
`category`	No	Optional category filter. One of: prices, employment, wages, productivity, injuries, time_use. A survey can appear under more than one category (CES under employment and wages). Omit to list all surveys.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`total`	No	Total surveys returned.
`surveys`	No	BLS survey programs matching the filter, sorted alphabetically by abbreviation.
`categoryFilter`	No	Category filter applied, if any. Absent when all surveys were listed.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 2, 2026

addedOutput schema / properties / surveys / items / properties / searchCoverage

Added value: +{
+  "description": "How bls_search_series reaches this survey: \"indexed\" when its offline index holds the survey's series (seriesIndexed counts them), \"composed\" when it builds the survey's SeriesIDs from code tables instead (OE without indexed OE rows), \"none\" when it cannot search the survey — fetch those series by SeriesID with bls_get_series. Absent while the catalog index is still loading at startup.",
+  "enum": [
+    "indexed",
+    "composed",
+    "none"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / surveys / items / properties / seriesIndexed

Added value: +{
+  "description": "Series of this survey in the offline index. Present only when searchCoverage is \"indexed\".",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

Changed2 schema fields changedNov 1, 2026

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_api_key`: BLS rejected the configured BLS_API_KEY as invalid. `service_unavailable`: BLS /surveys API is unreachable or returns a non-200 response. `serialization_failure`: BLS /surveys response cannot be parsed (malformed JSON or unexpected schema). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_api_key`: BLS rejected the configured BLS_API_KEY as invalid. `service_unavailable`: BLS /surveys API is unreachable or returns a non-200 response. `serialization_failure`: BLS /surveys response cannot be parsed as JSON. `upstream_timeout`: The live BLS request exceeds its shared 45-second operation budget. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "invalid_api_key",
-  "service_unavailable",
-  "serialization_failure"
-]New value: +[
+  "invalid_api_key",
+  "service_unavailable",
+  "serialization_failure",
+  "upstream_timeout"
+]

Changed1 schema field changedSep 24, 2026

changedInput schema / properties / category / description

Previous value: -"Optional category filter. One of: prices, employment, wages, productivity, injuries, time_use. Omit to list all surveys."New value: +"Optional category filter. One of: prices, employment, wages, productivity, injuries, time_use. A survey can appear under more than one category (CES under employment and wages). Omit to list all surveys."

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": [
+      "surveys",
+      "total"
+    ]
+  },
+  {
+    "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: `invalid_api_key`: BLS rejected the configured BLS_API_KEY as invalid. `service_unavailable`: BLS /surveys API is unreachable or returns a non-200 response. `serialization_failure`: BLS /surveys response cannot be parsed (malformed JSON or unexpected schema). Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "invalid_api_key",
+            "service_unavailable",
+            "serialization_failure"
+          ],
+          "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: -[
-  "surveys",
-  "total"
-]

Changed1 schema field changedJul 17, 2026

changedOutput schema / properties / surveys / items / properties / hasAnnualAverages / description

Previous value: -"True when the survey publishes annual average observations."New value: +"True when BLS reports that the survey publishes annual average observations. Advisory only: it does not predict whether a given series returns annual-average rows for bls_get_series with annual_average=true — LN, CE, LA and SM report true yet return none. Read annualAverageRows on that response for what actually came back."

Changed1 schema field changedJun 5, 2026

addedOutput schema / properties / categoryFilter

Added value: +{
+  "description": "Category filter applied, if any. Absent when all surveys were listed.",
+  "type": "string"
+}

First observedMay 25, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower; the description instead spends its words on the meaningful behavioral detail an agent needs — the three possible values of searchCoverage and what each implies for the next call. It does not mention result size, pagination, or whether the survey catalog is static, which keeps it from a 5.

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?

Purpose is front-loaded in the first clause, and the remaining sentences all carry routing or filtering information. It is dense — one long compound sentence about searchCoverage is harder to parse than a short list would be — but nothing is filler.

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?

With an output schema present and full schema coverage on the single parameter, the description only needs to supply the routing logic, and it does: how to pick a survey and what to call next for each coverage case. Nothing an agent needs to invoke this correctly is missing.

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 enum is fully documented in the schema, including the nuance that a survey can appear under multiple categories. The description restates the same category list with no added semantics (no defaults beyond 'omit', no ordering or matching behavior), so 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 BLS survey programs') plus what each row contains (abbreviation codes, full names, calculation-support and annual-average metadata). It is clearly separable from siblings because it names bls_search_series and bls_get_series as the downstream tools rather than overlapping with them.

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?

Gives an explicit trigger ('Use to discover which survey covers a topic before calling bls_search_series') and then spells out the routing decision: searchCoverage tells the agent whether bls_search_series can reach the survey, composes SeriesIDs from code tables, or requires bls_get_series by SeriesID. The alternative path is named with its condition, not left to inference.

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.