Skip to main content
Glama

List Census Predicate Values

census_list_predicate_values
Read-only

List the codes a Census filter dimension accepts, so a predicates map can be written without guessing. Answers the question left open when census_query_data or census_compare_geographies reports that a dimension was left unset. Which route a dimension takes depends on the vintage: NAICS and POPGROUP always publish a value list in the dataset dictionary, and on the current vintages EMPSZES, LFO, RCPSZES, TAXSTAT, and TYPOP publish none and are enumerated here against the live data endpoint instead, which needs the server's Census API key. A dictionary value list is a classification shared across Census products rather than a list of what one dataset serves, and roughly half of its codes typically return no rows anywhere — those are checked against the dataset's own published rows and dropped, a check that also reads the data endpoint and so needs the key; without a working key the dictionary list comes back unchecked, and the response source field says whether that check ran. The dictionary lists run to thousands of codes and are best narrowed with query. Pass the returned code as the dimension's value in predicates.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "predicate": "<predicate>",
      "dataset": "<dataset>"
    },
    "name": "census_list_predicate_values"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNoVintage year (default: latest available for the dataset).
limitNoMaximum codes per page (default: 50, max: 500). totalCount counts matches before offset and limit; nextOffset continues the list.
queryNoKeyword to narrow the list, matched case-insensitively against each code and label (e.g., "software" against NAICS2017, "exempt" against TAXSTAT). Omit to list from the start. NAICS and POPGROUP run to thousands of codes, so a keyword is the practical way to use them.
offsetNoMatching codes to skip in code order (default: 0). Follow nextOffset with the same predicate, dataset, year, query, geography_level and within_naics.
datasetYesDataset the dimension belongs to (e.g., "cbp", "nonemp", "ecnbasic", "dec/ddhca", "dec/ddhcb", "pep/charv", "acs/acs1/spp"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — "ddhca" is dec/ddhca, "charv" is pep/charv. Three-part codes such as acs/acs1/spp must be given in full. The response echoes the resolved code. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for.
predicateYesFilter dimension code to enumerate (e.g., "EMPSZES", "LFO", "POPGROUP", "NAICS2017"). Trimmed and uppercased, and the response echoes that spelling. The response notice of census_query_data names the dimensions a dataset declares, and census_search_variables finds them by keyword.
within_naicsNoIndustry code to scope the enumeration by, for dimensions the Census publishes per industry. On ecnbasic, TAXSTAT and TYPOP return only the all-establishments row until a NAICS sector is named — pass a sector code such as "62" (Health Care) or "42" (Wholesale Trade) and the result is complete for that industry alone. Ignored for dimensions with a published value list. Get sector codes by calling this tool on the dataset's own NAICS dimension. Blank is treated as omitted.
geography_levelNoGeography level for live enumeration (default: "us"). Codes can differ by level. Only levels whose dataset/year geography metadata permits a wildcard without concrete parents are supported, such as "county" on cbp. Dictionary lists remain dataset-wide and do not validate publication at this level.

Output Schema

NameRequiredDescriptionDefault
yearNoVintage year queried.
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when the list was truncated, when query matched no published code, when codes from the dataset dictionary could not be checked against its published rows, or when the codes returned are complete only for a named industry rather than for the dimension as a whole.
sourceNoWhere the codes came from. "live_query" is a wildcard group-by against the data endpoint, which returns only codes the dataset publishes. "dataset_dictionary_verified" is the dataset's published value map with the codes it serves no rows for removed. Plain "dataset_dictionary" is that map unchecked — every code in it is declared by the dataset, but some of them return nothing at any geography, and the notice says why the check did not run.
valuesNoCodes the dimension accepts, sorted by code.
datasetNoDataset queried.
predicateNoFilter dimension enumerated.
truncatedNoTrue when matching codes remain after the current page.
nextOffsetNoOffset for the next page; absent when no matching codes remain after this page.
totalCountNoCodes matched before the limit was applied.
geography_levelNoEffective live enumeration level. Absent for a dictionary list, which does not validate geography-specific publication.
predicate_labelNoLabel of the dimension itself (e.g., "Employment size of establishments code").

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / geography_level
      Added value: +{
      +  "description": "Geography level for live enumeration (default: \"us\"). Codes can differ by level. Only levels whose dataset/year geography metadata permits a wildcard without concrete parents are supported, such as \"county\" on cbp. Dictionary lists remain dataset-wide and do not validate publication at this level.",
      +  "type": "string"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum codes to return (default: 50, max: 500). totalCount says how many matched."New value: +"Maximum codes per page (default: 50, max: 500). totalCount counts matches before offset and limit; nextOffset continues the list."
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Matching codes to skip in code order (default: 0). Follow nextOffset with the same predicate, dataset, year, query, geography_level and within_naics.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `dataset_not_found`: Dataset code is missing or not recognized, even after case and shorthand resolution. `missing_api_key`: A dimension with no published value list is enumerated against the data endpoint, and CENSUS_API_KEY is not configured or the key is invalid. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error, was unreachable, or did not answer the enumeration within its 40-second limit across retries. `variables_unavailable`: The dataset's variables.json came back as HTML or unparseable, so the predicate cannot be checked against it. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `geography_not_supported`: An explicit live geography level is not listed by this dataset and year. `parent_required`: An explicit live geography level needs concrete parents even with a wildcard target. `dataset_not_found`: Dataset code is missing or not recognized, even after case and shorthand resolution. `missing_api_key`: A dimension with no published value list is enumerated against the data endpoint, and CENSUS_API_KEY is not configured or the key is invalid. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error, was unreachable, explicit geography metadata was unavailable, or upstream work exceeded the shared 50-second call budget or the enumeration local 40-second ceiling across retries. `variables_unavailable`: The dataset's variables.json came back as HTML or unparseable, so the predicate cannot be checked against it. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "dataset_not_found",
      -  "missing_api_key",
      -  "year_not_available",
      -  "predicate_not_supported",
      -  "not_a_filter_dimension",
      -  "no_values",
      -  "upstream_error",
      -  "variables_unavailable"
      -]New value: +[
      +  "geography_not_supported",
      +  "parent_required",
      +  "dataset_not_found",
      +  "missing_api_key",
      +  "year_not_available",
      +  "predicate_not_supported",
      +  "not_a_filter_dimension",
      +  "no_values",
      +  "upstream_error",
      +  "variables_unavailable"
      +]
    • addedOutput schema / properties / geography_level
      Added value: +{
      +  "description": "Effective live enumeration level. Absent for a dictionary list, which does not validate geography-specific publication.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / nextOffset
      Added value: +{
      +  "description": "Offset for the next page; absent when no matching codes remain after this page.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when totalCount exceeds the limit and the list was cut."New value: +"True when matching codes remain after the current page."
  2. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `dataset_not_found`: Dataset code is missing or not recognized, even after case and shorthand resolution. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error or was unreachable. `variables_unavailable`: The dataset's variables.json came back as HTML or unparseable, so the predicate cannot be checked against it. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `dataset_not_found`: Dataset code is missing or not recognized, even after case and shorthand resolution. `missing_api_key`: A dimension with no published value list is enumerated against the data endpoint, and CENSUS_API_KEY is not configured or the key is invalid. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error, was unreachable, or did not answer the enumeration within its 40-second limit across retries. `variables_unavailable`: The dataset's variables.json came back as HTML or unparseable, so the predicate cannot be checked against it. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "dataset_not_found",
      -  "year_not_available",
      -  "predicate_not_supported",
      -  "not_a_filter_dimension",
      -  "no_values",
      -  "upstream_error",
      -  "variables_unavailable"
      -]New value: +[
      +  "dataset_not_found",
      +  "missing_api_key",
      +  "year_not_available",
      +  "predicate_not_supported",
      +  "not_a_filter_dimension",
      +  "no_values",
      +  "upstream_error",
      +  "variables_unavailable"
      +]
  3. Changed3 schema fields changed
    • changedInput schema / properties / dataset / description
      Previous value: -"Dataset the dimension belongs to (e.g., \"cbp\", \"nonemp\", \"ecnbasic\", \"dec/ddhca\", \"pep/charv\", \"acs/acs1/spp\"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — \"ddhca\" is dec/ddhca, \"charv\" is pep/charv. Three-part codes such as acs/acs1/spp must be given in full. The response echoes the resolved code. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for."New value: +"Dataset the dimension belongs to (e.g., \"cbp\", \"nonemp\", \"ecnbasic\", \"dec/ddhca\", \"dec/ddhcb\", \"pep/charv\", \"acs/acs1/spp\"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — \"ddhca\" is dec/ddhca, \"charv\" is pep/charv. Three-part codes such as acs/acs1/spp must be given in full. The response echoes the resolved code. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `dataset_not_found`: Dataset code is missing or not recognized, even after case and shorthand resolution. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error or was unreachable. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `dataset_not_found`: Dataset code is missing or not recognized, even after case and shorthand resolution. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error or was unreachable. `variables_unavailable`: The dataset's variables.json came back as HTML or unparseable, so the predicate cannot be checked against it. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "dataset_not_found",
      -  "year_not_available",
      -  "predicate_not_supported",
      -  "not_a_filter_dimension",
      -  "no_values",
      -  "upstream_error"
      -]New value: +[
      +  "dataset_not_found",
      +  "year_not_available",
      +  "predicate_not_supported",
      +  "not_a_filter_dimension",
      +  "no_values",
      +  "upstream_error",
      +  "variables_unavailable"
      +]
  4. Changed3 schema fields changed
    • changedInput schema / properties / dataset / description
      Previous value: -"Dataset the dimension belongs to (e.g., \"cbp\", \"nonemp\", \"ecnbasic\", \"dec/ddhca\", \"pep/charv\"). Use census_list_datasets to discover valid values. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for."New value: +"Dataset the dimension belongs to (e.g., \"cbp\", \"nonemp\", \"ecnbasic\", \"dec/ddhca\", \"pep/charv\", \"acs/acs1/spp\"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — \"ddhca\" is dec/ddhca, \"charv\" is pep/charv. Three-part codes such as acs/acs1/spp must be given in full. The response echoes the resolved code. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for."
    • changedInput schema / properties / predicate / description
      Previous value: -"Filter dimension code to enumerate (e.g., \"EMPSZES\", \"LFO\", \"POPGROUP\", \"NAICS2017\"). Case-sensitive. The response notice of census_query_data names the dimensions a dataset declares, and census_search_variables finds them by keyword."New value: +"Filter dimension code to enumerate (e.g., \"EMPSZES\", \"LFO\", \"POPGROUP\", \"NAICS2017\"). Trimmed and uppercased, and the response echoes that spelling. The response notice of census_query_data names the dimensions a dataset declares, and census_search_variables finds them by keyword."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `dataset_not_found`: Dataset code is not recognized. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error or was unreachable. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `dataset_not_found`: Dataset code is missing or not recognized, even after case and shorthand resolution. `year_not_available`: The dataset does not serve the requested vintage year. `predicate_not_supported`: The predicate code is not a variable in this dataset and year. `not_a_filter_dimension`: The code is not one of the dimensions the dataset filters on, so it takes no value list. `no_values`: The dimension returned no codes for the scope requested. `upstream_error`: Census API returned an error or was unreachable. Other values are possible when a failure originates below the handler."
  5. Changed4 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum codes to return (default: 50, max: 500)."New value: +"Maximum codes to return (default: 50, max: 500). totalCount says how many matched."
    • addedInput schema / properties / limit / maximum
      Added value: +500
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
  6. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Beyond readOnlyHint/openWorldHint it discloses live behavior that matters: the server's Census API key is needed for the data-endpoint route and for the row-publication check, without a working key the dictionary list comes back unchecked, the response's source field says which path ran, and roughly half of dictionary codes typically return no rows anywhere. It stops short of describing the response shape (partly expected, since an output schema exists) so a 4 rather than 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?

The purpose and the precondition for using it are front-loaded and most sentences carry non-redundant facts, but the description runs long and the dictionary-vs-live-route sentence packs several independent claims that slow down a scanning agent.

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 an eight-parameter, open-world-off read tool with full schema coverage and an output schema, this covers the routing logic, key requirements, fallback behavior and pagination-adjacent narrowing — nothing essential to a correct call is missing.

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 baseline is 3; the description still adds meaning about interactions the schema only touches on — that dataset and year must match the vintage the values are for, and that within_naics only matters when the dimension is live-enumerated rather than dictionary-backed.

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?

"List the codes a Census filter dimension accepts, so a predicates map can be written without guessing" names a specific verb and resource plus the outcome, and the mention of census_query_data / census_compare_geographies reporting an unset dimension separates it from census_search_variables and census_list_datasets.

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?

It states exactly when to reach for this tool (a dimension was left unset, or one must be chosen before writing predicates), which dimensions are enumerated here versus from a dictionary, and the operational caveats — narrow huge NAICS/POPGROUP lists with query, pass within_naics a sector code for ecnbasic/TAXSTAT/TYPOP, and feed the returned code into the predicates value.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.