census-mcp-server

Get Census Variable Metadata

census_get_variable

Read-only

Fetch full metadata for one or more Census variable codes — label, concept group, predicate type, the table's universe, and margin-of-error sibling references. Use to confirm a variable code before building a query, or to look up what a known code means. On ACS datasets it returns estimate_code and moe_code sibling references so you can request both without a separate search, and a margin-of-error code carries attribute_of and attribute_type MARGIN_OF_ERROR as the Census publishes them; the ACS comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile) and the other dataset families publish no margins of error and carry none of these fields. It also resolves the annotation and flag columns the data tools accept, such as B19013_001EA or EMP_F, naming the column each one belongs to, and predicate codes such as NAICS2017 or SEX, confirming a filter dimension exists in a dataset before a query uses it — for the values a dimension accepts rather than the dimension itself, call census_list_predicate_values.

Input Schema

TableJSON Schema

Name	Required	Description
`year`	No	Vintage year (default: latest available for the dataset).
`dataset`	No	Dataset the variables belong to (default: "acs/acs5"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — "acs5" is acs/acs5, "pl" is dec/pl. Three-part codes such as acs/acs5/profile must be given in full. The response echoes the resolved code.
`variables`	Yes	One or more variable codes to look up (e.g., ["B19013_001E", "B19013_001M"]). Codes are trimmed and matched regardless of case, and the response echoes the dataset's own spelling — uppercase everywhere except the comparison profiles' significance columns (e.g., CP03_2024to2019_062SS).

Output Schema

TableJSON Schema

Name	Required	Description
`year`	No	Vintage year queried.
`error`	No	Present when the call failed. Absent on success.
`dataset`	No	Dataset queried.
`variables`	No	Variable metadata in the same order as the input array.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedSep 25, 2026

changedInput schema / properties / dataset / description

Previous value: -"Dataset the variables belong to (default: \"acs/acs5\"). Use census_list_datasets to discover valid values."New value: +"Dataset the variables belong to (default: \"acs/acs5\"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — \"acs5\" is acs/acs5, \"pl\" is dec/pl. Three-part codes such as acs/acs5/profile must be given in full. The response echoes the resolved code."

changedInput schema / properties / variables / description

Previous value: -"One or more variable codes to look up (e.g., [\"B19013_001E\", \"B19013_001M\"]). Variable codes are case-sensitive."New value: +"One or more variable codes to look up (e.g., [\"B19013_001E\", \"B19013_001M\"]). Codes are trimmed and matched regardless of case, and the response echoes the dataset's own spelling — uppercase everywhere except the comparison profiles' significance columns (e.g., CP03_2024to2019_062SS)."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `variable_not_found`: One or more variable codes were not found in the dataset and year. `dataset_not_found`: Dataset code is not recognized. `year_not_available`: The dataset does not serve the requested vintage year. `variables_unavailable`: Variable metadata endpoint is unreachable or returned an unparseable response. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `variable_not_found`: One or more variable codes were not found in the dataset and year. `dataset_not_found`: Dataset code is not recognized, even after case and shorthand resolution. `year_not_available`: The dataset does not serve the requested vintage year. `variables_unavailable`: Variable metadata — the dataset's variables.json, groups.json, or an attribute column's own entry — could not be fetched or parsed. Other values are possible when a failure originates below the handler."

addedOutput schema / properties / variables / items / properties / attribute_of

Added value: +{
+  "description": "For an annotation, flag, or margin-of-error column, the column it belongs to, as the Census publishes it (e.g., \"B19013_001E\" for B19013_001EA or B19013_001M). Absent on ordinary variables.",
+  "type": "string"
+}

addedOutput schema / properties / variables / items / properties / attribute_type

Added value: +{
+  "description": "For an annotation, flag, or margin-of-error column, its kind as the Census publishes it (e.g., \"ANNOTATION\", \"FLAG\", \"MARGIN_OF_ERROR\"). Absent on ordinary variables.",
+  "type": "string"
+}

changedOutput schema / properties / variables / items / properties / concept / description

Previous value: -"Concept group the variable belongs to."New value: +"Concept of the table the variable belongs to. Absent for a column shared across tables, such as GEO_ID, whose concept joins every table it appears in, and for a column the dataset publishes no concept for, such as STATE."

changedOutput schema / properties / variables / items / properties / estimate_code / description

Previous value: -"Estimate sibling variable code when this is a margin-of-error variable. ACS datasets only — no other family publishes margins of error."New value: +"Estimate sibling variable code when this is a margin-of-error variable. ACS datasets only, apart from the comparison profiles — no other dataset publishes margins of error."

changedOutput schema / properties / variables / items / properties / moe_code / description

Previous value: -"Margin-of-error sibling code when this is an estimate variable. Include both in census_query_data for complete data. ACS datasets only — on other families an E-final code is an ordinary code with no margin-of-error sibling, so the field is absent."New value: +"Margin-of-error sibling code when this is an estimate variable. Include both in census_query_data for complete data. ACS datasets only, apart from the comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile) — there and on other families an E-final code has no margin-of-error sibling, so the field is absent."

changedOutput schema / properties / variables / items / properties / universe / description

Previous value: -"Universe the variable applies to (e.g., \"Households\", \"People 25 years and over\")."New value: +"Universe of the variable's table (e.g., \"Households\", \"Population 25 years and over\"). Absent when the table publishes none — the ACS subject, profile, and selected population profile tables, dec/dp, the business datasets, pep/charv, and every ACS and dec/pl vintage before 2020 publish none — and for a column that belongs to no single table."

changedOutput schema / properties / variables / items / required

Previous value: -[
-  "variable_code",
-  "label",
-  "concept",
-  "predicate_type"
-]New value: +[
+  "variable_code",
+  "label",
+  "predicate_type"
+]

First observedSep 19, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only nature is covered. The description adds substantial behavioral context beyond annotations: it discloses that ACS datasets return estimate_code and moe_code sibling references, that MOE codes carry attribute_of/attribute_type MARGIN_OF_ERROR, that comparison profiles and other dataset families omit MOE fields entirely, and that annotation/flag columns are resolved to their owning columns. This is rich, detailed behavior an agent cannot infer from the schema or annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a dense, multi-clause sentence with several parenthetical asides and em-dash digressions. While every detail is arguably relevant, the structure is not front-loaded or easily skimmable; the key usage guidance appears only after a long list of return fields. It is thorough but not concise, and a more bulleted or scannable layout would improve clarity without losing information.

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?

Given that an output schema exists, the tool definition does not need to explain return values in detail. The description covers all essential non-obvious contexts: dataset-family differences (ACS vs. comparison profiles vs. others), MOE behavior, annotation/flag column resolution, and predicate dimension validation. With the read-only annotation and full parameter schema, nothing an agent needs to call 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 description coverage is 100%, so each parameter (year, dataset, variables) already has a clear description in the input schema. The main description adds no further parameter-level meaning – it repeats the variable-code matching behavior that the schema already documents. Baseline 3 is appropriate because the schema does the heavy lifting and the description does not need to compensate.

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 opens with a specific verb ('Fetch') and resource ('full metadata for one or more Census variable codes') followed by a concrete list of returned metadata (label, concept group, predicate type, universe, MOE references). It also explicitly distinguishes itself from siblings: 'look up what a known code means' versus census_search_variables, and 'call census_list_predicate_values' for values rather than dimensions. An agent can instantly tell which tool does what.

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?

The description gives explicit when-to-use guidance: 'Use to confirm a variable code before building a query, or to look up what a known code means.' It also names a direct alternative and the condition that selects it: 'for the values a dimension accepts rather than the dimension itself, call census_list_predicate_values.' This leaves no ambiguity about when to pick this over a sibling.

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

All census-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.