bls-labor-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'name': {'type': 'string', 'description': 'Optional dataframe name to describe a single dataframe â\x80\x94 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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['dataframes']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_unavailable', 'invalid_dataframe_name'], 'description': '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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'dataframes': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'source_tool', 'query_params', 'created_at', 'expires_at', 'row_count', 'column_schema'], 'properties': {'name': {'type': 'string', 'description': 'Canvas table name â\x80\x94 df_XXXXX_XXXXX, or the register_as name given.'}, 'row_count': {'type': 'number', 'description': 'Rows materialized in the dataframe.'}, 'created_at': {'type': 'string', 'description': 'ISO 8601 creation timestamp.'}, 'expires_at': {'type': 'string', 'description': 'ISO 8601 expiry timestamp (sliding TTL).'}, 'source_tool': {'type': 'string', 'description': 'Tool that produced this dataframe.'}, 'query_params': {'type': 'object', 'description': 'Input parameters the source tool was called with.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'column_schema': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'type', 'nullable'], 'properties': {'name': {'type': 'string', 'description': 'Column name.'}, 'type': {'type': 'string', 'description': '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.'}, 'nullable': {'type': 'boolean', 'description': 'Whether the column permits NULL.'}}, 'description': 'Schema descriptor for one column in the dataframe.', 'additionalProperties': False}, 'description': 'Column schema â\x80\x94 all BLS dataframe columns are nullable.'}}, 'description': 'Metadata for one canvas dataframe.', 'additionalProperties': False}, 'description': 'Active dataframes for this tenant, newest first.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['sql'], 'properties': {'sql': {'type': 'string', 'minLength': 1, 'description': "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 â\x80\x94 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': {'type': 'integer', 'maximum': 10000, 'minimum': 0, 'description': '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': {'type': 'integer', 'default': 1000, 'maximum': 10000, 'minimum': 1, 'description': 'Hard cap on rows materialized in the response (default 1000, max 10000). Full results live on-canvas under register_as when provided.'}, 'register_as': {'type': 'string', 'description': 'When set, persist the query result as a new dataframe under this name. Fresh TTL â\x80\x94 not inherited from parent tables. Use to chain analyses without re-running source SQL or consuming additional BLS quota.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['columns', 'row_count', 'rows']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The preview or row_limit cap that was applied.'}, 'rows': {'type': 'array', 'items': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'description': 'Materialized rows, bounded by preview / row_limit.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_unavailable'], '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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of rows returned inline.'}, 'notice': {'type': 'string', 'description': 'Guidance when results were capped by preview or row_limit â\x80\x94 names which parameter was the binding limiter and suggests how to retrieve the rest. Absent when all rows fit in the response.'}, 'columns': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Column names in projection order.'}, 'row_count': {'type': 'number', 'description': 'Rows materialized by the query. Exact when register_as is used; otherwise equals row_limit when truncated is true.'}, 'truncated': {'type': 'boolean', 'description': 'True when the returned rows were capped.'}, 'expires_at': {'type': 'string', 'description': 'ISO 8601 expiry for the newly registered dataframe, when applicable.'}, 'registered_as': {'type': 'string', 'description': 'Set when register_as was supplied and the result was materialized.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['series_ids'], 'properties': {'series_ids': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'maxItems': 50, 'minItems': 1, 'description': 'One or more BLS SeriesIDs (1â\x80\x9350). Each consumes one daily API query. Use bls_search_series to resolve concepts to SeriesIDs. Recommended: â\x89¤10 series.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['results', 'succeeded', 'failed']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_api_key', 'quota_exceeded', 'series_locked'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_api_key`: BLS rejected the configured BLS_API_KEY as invalid, and no requested series returned an observation. `quota_exceeded`: The BLS API 500 query/day limit has been reached, and no requested series returned an observation. `series_locked`: The BLS database is temporarily locked for the requested series, and no requested series returned an observation. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'failed': {'type': 'array', 'items': {'type': 'object', 'required': ['seriesId', 'error'], 'properties': {'error': {'type': 'string', 'description': 'Error message. Common values: "Series does not exist" or "Invalid Series" (invalid SeriesID â\x80\x94 use bls_search_series to find valid IDs), "No observations returned" (series exists but has no current data). The generic "Your request has failed. Please check your input parameters, and try your request again." means BLS rejected the request itself twice, the second time without catalog metadata, rather than naming the SeriesID. A quota, API-key, or database-lock failure lands here only when another series returned an observation; notice then names its reason and recovery.'}, 'seriesId': {'type': 'string', 'description': 'SeriesID that failed.'}}, 'description': 'A series that could not be fetched, e.g. due to an invalid SeriesID or empty data window.', 'additionalProperties': False}, 'description': 'Series that failed to fetch. Inspect seriesId and error for per-item details. Not-found series appear here rather than as a tool-level error.'}, 'notice': {'type': 'string', 'description': 'Guidance when one or more series failed â\x80\x94 bls_search_series for a SeriesID BLS rejected, or the reason and recovery for a quota, API-key, or database-lock failure that left other series answered. Absent when all series returned data.'}, 'results': {'type': 'array', 'items': {'type': 'object', 'required': ['seriesId'], 'properties': {'area': {'type': 'string', 'description': 'Geographic area when returned by the API.'}, 'item': {'type': 'string', 'description': 'Item/subject when returned by the API.'}, 'title': {'type': 'string', 'description': 'Series name when returned by the API.'}, 'seasonal': {'type': 'string', 'description': 'Seasonality indicator when returned by the API.'}, 'seriesId': {'type': 'string', 'description': 'BLS SeriesID.'}, 'latestObservation': {'type': 'object', 'required': ['year', 'period', 'value', 'available'], 'properties': {'year': {'type': 'string', 'description': 'Observation year (e.g. "2024").'}, 'value': {'type': 'string', 'description': 'Raw observation value from BLS. The literal "-" means unavailable; check available before arithmetic and read footnotes for the reason.'}, 'period': {'type': 'string', 'description': 'Observation period code (e.g. "M12" for December, "Q01" for Q1).'}, 'available': {'type': 'boolean', 'description': 'False when BLS published the "-" missing-value sentinel for this period.'}, 'footnotes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Footnote codes and text, when present.'}, 'periodName': {'type': 'string', 'description': 'Human-readable period name (e.g. "December").'}}, 'description': 'Most recent observation.', 'additionalProperties': False}}, 'description': 'Latest observation result for one BLS series.', 'additionalProperties': False}, 'description': 'Successfully fetched series with their latest observations. Series that failed appear in failed[] instead.'}, 'succeeded': {'type': 'number', 'description': 'Number of series with a successfully fetched observation.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['series_ids'], 'properties': {'end_year': {'type': 'integer', 'maximum': 2100, 'minimum': 1900, 'description': 'End year for the data range (inclusive). Supplying it without start_year is rejected before the request â\x80\x94 BLS applies no default start year alongside an explicit end year. Pair it with start_year, or omit both for the API default window.'}, 'series_ids': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}, 'maxItems': 50, 'minItems': 1, 'description': 'One or more BLS SeriesIDs (1â\x80\x9350). The entire batch counts as one API query. Use bls_search_series to resolve concepts to SeriesIDs.'}, 'start_year': {'type': 'integer', 'maximum': 2100, 'minimum': 1900, 'description': 'Start year for the data range (inclusive). The BLS API allows up to 20 years per request and requires both bounds or neither: supplying start_year alone resolves end_year to the current year, capped at start_year + 19 so the window stays inside the 20-year limit. Omit both for the API default (typically 3â\x80\x9320 years depending on survey).'}, 'calculations': {'type': 'boolean', 'description': 'When true, request BLS-computed period-over-period calculations. The flag is a single boolean (you cannot select an individual calculation type), but the API returns whichever the survey supports and omits the rest â\x80\x94 CPI and PPI return percent change only (the inflation rate), and a survey that supports neither simply returns its observations without calculation fields. Requesting calculations never fails, so it is always safe to set; consult bls_list_surveys (allowsNetChange / allowsPercentChange) only to predict which fields will come back. Monthly-cadence series return each supported change type over 1, 3, 6, and 12-month intervals; other cadences return a subset. A series served from the local observation mirror, when the server runs one, carries no calculation fields; enrichment.calculationsApplied is then false and notice names it.'}, 'annual_average': {'type': 'boolean', 'default': False, 'description': 'When true, add each year\'s annual-average row to the observations. An annual average is the mean of that year\'s real periods, returned as an extra row named "Annual" with period M13 (monthly series), Q05 (quarterly) or S03 (semiannual) â\x80\x94 not an additional month or quarter, so it must be excluded from any sum or average over observations. Defaults to false, which returns real periods only; check available before aggregating. Independent of start_year/end_year. Surveys that publish no annual averages return the same rows either way; enrichment.annualAverageRows reports how many rows were actually added.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['series', 'spilled', 'totalObservations', 'availableObservations', 'unavailableObservations', 'seriesRequested', 'annualAverageApplied']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_api_key', 'quota_exceeded', 'request_rejected', 'series_not_found', 'series_locked', 'no_data_for_period', 'calculations_not_supported', 'canvas_unavailable', 'canvas_registration_failed'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_api_key`: BLS rejected the configured BLS_API_KEY as invalid. `quota_exceeded`: The BLS API 500 query/day limit has been reached. `request_rejected`: BLS returned a non-success status with a message matching no known failure mode, both for the request and for its automatic re-issue without catalog metadata â\x80\x94 e.g. a rejected combination of request parameters. `series_not_found`: No requested series returned data and at least one SeriesID does not exist. A batch mixing an invalid SeriesID with one BLS has no data for lands here too, and names both in the message and recovery hint. `series_locked`: The BLS database is temporarily locked for the requested series. `no_data_for_period`: The requested year range is unusable before the request â\x80\x94 start_year after end_year, a span of 20 years or more, or end_year without start_year â\x80\x94 or BLS returned data for none of the requested series over the range. `calculations_not_supported`: calculations=true was requested for a survey that does not support it. `canvas_unavailable`: The result set exceeds the inline budget and canvas (DuckDB) is not configured. `canvas_registration_failed`: The result set exceeds the inline budget and canvas is configured, but registering the dataframe failed. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': "Guidance for agents â\x80\x94 names any SeriesID that returned zero observations with its reason (including a failed live fallback's reason and recovery for a SeriesID the local observation mirror does not hold), names mirror-served series that lack requested calculations, reports a resolved end_year the 20-year window capped, and reports the bls_dataframe_describe then bls_dataframe_query workflow when results spill to canvas. Absent when every requested series returned data over the window as asked and it all fit inline."}, 'series': {'type': 'array', 'items': {'type': 'object', 'required': ['seriesId', 'observationCount', 'availableObservationCount', 'observations'], 'properties': {'area': {'type': 'string', 'description': 'Geographic area when returned by the API.'}, 'item': {'type': 'string', 'description': 'Item/subject when returned by the API.'}, 'title': {'type': 'string', 'description': 'Series name when returned by the API.'}, 'seasonal': {'type': 'string', 'description': 'Seasonality indicator when returned by the API.'}, 'seriesId': {'type': 'string', 'description': 'BLS SeriesID.'}, 'observations': {'type': 'array', 'items': {'type': 'object', 'required': ['year', 'period', 'value', 'available'], 'properties': {'year': {'type': 'string', 'description': 'Observation year.'}, 'value': {'type': 'string', 'description': 'Raw observation value from BLS. The literal "-" means unavailable; check available before arithmetic and read footnotes for the reason.'}, 'period': {'type': 'string', 'description': 'BLS period code: M01â\x80\x93M12 are months, Q01â\x80\x93Q04 quarters, S01â\x80\x93S02 semiannual halves. M13, Q05 and S03 are not further periods â\x80\x94 each is the mean of that year\'s real observations, named "Annual", and appears only when annual_average is true. Exclude them from any sum or average over observations.'}, 'available': {'type': 'boolean', 'description': 'False when BLS published the "-" missing-value sentinel for this period.'}, 'footnotes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Footnote codes and text, when present.'}, 'periodName': {'type': 'string', 'description': 'Human-readable period name.'}, 'netChange1Month': {'type': 'string', 'description': '1-month net change (when calculations=true).'}, 'netChange3Month': {'type': 'string', 'description': '3-month net change (when calculations=true).'}, 'netChange6Month': {'type': 'string', 'description': '6-month net change (when calculations=true).'}, 'pctChange1Month': {'type': 'string', 'description': '1-month percent change (when calculations=true).'}, 'pctChange3Month': {'type': 'string', 'description': '3-month percent change (when calculations=true).'}, 'pctChange6Month': {'type': 'string', 'description': '6-month percent change (when calculations=true).'}, 'netChange12Month': {'type': 'string', 'description': '12-month net change (when calculations=true).'}, 'pctChange12Month': {'type': 'string', 'description': '12-month percent change (when calculations=true).'}}, 'description': 'One observation data point.', 'additionalProperties': False}, 'description': 'Inline observations. All observations when no spillover; preview rows when spilled to canvas.'}, 'observationCount': {'type': 'number', 'description': 'Total period rows for this series, including unavailable BLS placeholder rows. When spilled to canvas, all rows are on the dataframe; inline only shows a preview.'}, 'availableObservationCount': {'type': 'number', 'description': 'Rows with a published numeric value, excluding the BLS "-" sentinel.'}}, 'description': 'Time-series data for one BLS series.', 'additionalProperties': False}, 'description': 'Series data, in request order.'}, 'dataset': {'type': 'object', 'required': ['name', 'row_count', 'expires_at'], 'properties': {'name': {'type': 'string', 'description': 'Canvas table name (df_XXXXX_XXXXX). Pass to bls_dataframe_describe first to inspect column_schema, then use it in bls_dataframe_query SQL.'}, 'row_count': {'type': 'number', 'description': 'Total rows in the canvas table.'}, 'expires_at': {'type': 'string', 'description': 'ISO 8601 expiry timestamp (sliding 24h window).'}}, 'description': 'Canvas dataframe handle â\x80\x94 present when the observation volume exceeded the inline budget. Call bls_dataframe_describe with dataset.name to inspect column_schema, then use that table name in bls_dataframe_query SQL across the full data.', 'additionalProperties': False}, 'spilled': {'type': 'boolean', 'description': 'True when results spilled to canvas due to inline budget overflow.'}, 'endYearApplied': {'type': 'number', 'description': 'End year applied to the query. Resolved from start_year when end_year was omitted, so it can differ from the requested range; notice names the cap when the 20-year window decided it. Absent when no year range was in effect.'}, 'seriesRequested': {'type': 'number', 'description': 'Number of SeriesIDs requested. Do not compare it against series[] length to find empty series â\x80\x94 a SeriesID that returned no data is still listed in series[] with observationCount 0. Check observationCount per entry, or read notice, which names every SeriesID that came back empty.'}, 'startYearApplied': {'type': 'number', 'description': 'Start year applied to the query, whether it was served live or from the local observation mirror. Absent when no year range was in effect.'}, 'annualAverageRows': {'type': 'number', 'description': 'How many observations across all series are annual-average rows (period M13/Q05/S03). Present only when annual_average is true; 0 means none of the requested surveys publish annual averages.'}, 'totalObservations': {'type': 'number', 'description': 'Total observation rows across all requested series.'}, 'calculationsApplied': {'type': 'boolean', 'description': 'Whether BLS net/percent-change calculations were applied. True when calculations=true reached BLS for every returned series; false when calculations=false, or when the local observation mirror served a series, whose rows carry no calculations â\x80\x94 notice then names those series. Absent when calculations was omitted.'}, 'annualAverageApplied': {'type': 'boolean', 'description': 'Whether annual-average rows were requested. When false, observations hold real periods only; filter on available before aggregation.'}, 'availableObservations': {'type': 'number', 'description': 'Rows with a published numeric value.'}, 'unavailableObservations': {'type': 'number', 'description': 'Rows carrying the BLS "-" missing-value sentinel.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'category': {'enum': ['prices', 'employment', 'wages', 'productivity', 'injuries', 'time_use'], 'type': 'string', 'description': '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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['surveys', 'total']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_api_key', 'service_unavailable', 'serialization_failure'], '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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'total': {'type': 'number', 'description': 'Total surveys returned.'}, 'surveys': {'type': 'array', 'items': {'type': 'object', 'required': ['abbreviation', 'name', 'allowsNetChange', 'allowsPercentChange', 'hasAnnualAverages'], 'properties': {'name': {'type': 'string', 'description': 'Full survey name (e.g. CPI - All Urban Consumers).'}, 'abbreviation': {'type': 'string', 'description': 'Two-character survey abbreviation (e.g. CU, CE, LN).'}, 'allowsNetChange': {'type': 'boolean', 'description': 'True when the survey supports BLS-computed net change via calculations=true.'}, 'hasAnnualAverages': {'type': 'boolean', 'description': '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 â\x80\x94 LN, CE, LA and SM report true yet return none. Read annualAverageRows on that response for what actually came back.'}, 'allowsPercentChange': {'type': 'boolean', 'description': 'True when the survey supports BLS-computed percent change via calculations=true.'}}, 'description': 'A BLS survey program entry.', 'additionalProperties': False}, 'description': 'BLS survey programs matching the filter, sorted alphabetically by abbreviation.'}, 'categoryFilter': {'type': 'string', 'description': 'Category filter applied, if any. Absent when all surveys were listed.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['query'], 'properties': {'area': {'type': 'string', 'description': 'State name, MSA name, or FIPS area code to narrow results to a geographic area â\x80\x94 a case-insensitive substring of the area name, title, or SeriesID. Omit for national series, which then rank first among equal matches.'}, 'limit': {'type': 'integer', 'default': 10, 'maximum': 50, 'minimum': 1, 'description': 'Maximum number of results to return (1â\x80\x9350, default 10).'}, 'query': {'type': 'string', 'minLength': 1, 'description': 'Natural language or keyword query (e.g. "unemployment rate", "CPI food", "nonfarm payrolls"). Also accepts a SeriesID directly for exact lookup.'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 0, 'description': 'Number of ranked results to skip, for paging past the first page (default 0). Pass nextOffset from the previous response to get the next page.'}, 'survey': {'type': 'string', 'description': 'Two-letter LABSTAT survey abbreviation to filter results, case-insensitive (e.g. CU for CPI, CE for CES, LN for CPS, LA for LAUS, JT for JOLTS). Indexed surveys: CU, AP, CE, LN, LA, PC, WP, JT, EC, PR, MP, CW, CM, CI; OE (OEWS) only when the server sets BLS_CATALOG_INCLUDE_OES=true. Omit to search all indexed surveys.'}, 'seasonal_adjustment': {'type': 'boolean', 'description': 'When true, return only seasonally adjusted series. When false, return only not-seasonally-adjusted. Omit to return both.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['series', 'totalCount', 'capped', 'catalogSize', 'effectiveQuery', 'limitApplied', 'offsetApplied']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The result limit that capped the returned list.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['catalog_unavailable'], 'description': 'Machine-readable failure mode. Declared by this tool: `catalog_unavailable`: The catalog index failed to load at startup. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of series returned in this response.'}, 'capped': {'type': 'boolean', 'description': 'True when the FTS candidate pool, after the survey/area/seasonal filters, reached the internal cap (~1000). totalCount is then a lower bound and offset paging stops at the pool. Narrow the query, add filters, or use a direct SeriesID to get an exact count.'}, 'notice': {'type': 'string', 'description': 'Guidance on the result: the survey is not in the offline index, the offset is past the last result, nothing matched, which offset fetches the next page, or, on the last page of a capped list, that other series may also match. Absent when this page ends an uncapped list with results.'}, 'series': {'type': 'array', 'items': {'type': 'object', 'required': ['seriesId', 'title', 'survey', 'seasonal'], 'properties': {'area': {'type': 'string', 'description': 'Geographic area name, when decoded.'}, 'item': {'type': 'string', 'description': 'Item or subject name, when decoded.'}, 'title': {'type': 'string', 'description': 'Plain-language series name.'}, 'survey': {'type': 'string', 'description': 'Survey abbreviation (e.g. CU, CE, LN).'}, 'seasonal': {'type': 'string', 'description': 'Seasonality descriptor matching the data-tool form: "Seasonally Adjusted" or "Not Seasonally Adjusted".'}, 'seriesId': {'type': 'string', 'description': 'BLS SeriesID â\x80\x94 pass to bls_get_series or bls_get_latest to fetch data.'}, 'frequency': {'type': 'string', 'description': 'Publication frequency â\x80\x94 "Monthly", "Semi-Annual", "Quarterly", or "Annual" â\x80\x94 for CU, CW, and LN, which publish one series at several frequencies under the same title. Absent for other surveys.'}}, 'description': 'A matching BLS series entry.', 'additionalProperties': False}, 'description': 'Matching series, ordered by relevance.'}, 'truncated': {'type': 'boolean', 'description': 'True when ranked results remain past this page; nextOffset fetches them.'}, 'areaFilter': {'type': 'string', 'description': 'Area filter applied, trimmed. Absent when no area filter was passed or it was blank.'}, 'nextOffset': {'type': 'number', 'description': 'Offset of the next page. Present only when truncated is true.'}, 'totalCount': {'type': 'number', 'description': 'Total ranked results after every filter (area included), before limit and offset. A lower bound when capped is true â\x80\x94 the catalog index may contain more matching series.'}, 'catalogSize': {'type': 'number', 'description': 'Total series in the loaded catalog index. Distinguishes an empty-result search from a failed catalog load.'}, 'limitApplied': {'type': 'number', 'description': 'Result limit in effect (defaults to 10 when omitted).'}, 'surveyFilter': {'type': 'string', 'description': 'Survey filter applied, trimmed and uppercased. Absent when no survey filter was passed or it was blank.'}, 'offsetApplied': {'type': 'number', 'description': 'Offset in effect (defaults to 0 when omitted).'}, 'effectiveQuery': {'type': 'string', 'description': 'Query string as the server received and searched on. Confirms interpretation for self-correction.'}, 'seasonalFilter': {'type': 'boolean', 'description': 'Seasonal-adjustment filter applied, if any. Absent when not passed.'}}, 'additionalProperties': False}