census-mcp-server

Compare Census Geographies

census_compare_geographies

Read-only

Compare one or more variables across multiple geographies at the same level — all counties in a state, all states nationally, or a named set of specific geographies. Results are sorted and ranked. Covers queries like "rank states by poverty rate", "compare median income across WA counties", or "which census tracts in King County have the highest renter rate." Omit within to compare all geographies nationally at the level. Suppressed values are decoded to human-readable labels rather than passed through as raw negative sentinels. On the business datasets (cbp, ecnbasic, nonemp), pep/charv, and dec/ddhca, use predicates to rank within one industry, size class, or population group — a comparison that omits one ranks on a default the Census API picks, which is an all-categories total on some dimensions and a single category on others. Each row names the defaults that were applied in applied_filters, and census_list_predicate_values enumerates the codes a dimension accepts. A dataset that publishes several records per geography cannot be ranked until one is pinned: pep/charv publishes an April estimates base and a July estimate, so a comparison that pins neither fails with ambiguous_rows rather than giving every geography two ranks — pass predicates {"MONTH": "7"} for the July estimate.

Input Schema

TableJSON Schema

Name	Required	Description
`year`	No	Vintage year (default: latest available for the dataset).
`limit`	No	Maximum geographies to return (default: 50, max: 500). When results are truncated, total_count indicates how many matched.
`within`	No	State FIPS to constrain results (e.g., "53" to compare counties or tracts within WA only). Omit to compare all geographies at the level nationally. Use census_resolve_geography to get state_fips. Pass "*" to span every state. Blank is treated as omitted.
`dataset`	No	Dataset to query (default: "acs/acs5"). Use census_list_datasets for valid values.
`sort_by`	No	Variable code to sort by (default: first variable in the list). Must be one of the requested variable codes.
`sort_dir`	No	Sort direction (default: "desc" — highest value first).
`variables`	Yes	Variable codes to compare (e.g., ["B17001_002E", "B17001_001E"]). On ACS datasets, add the margin-of-error counterpart of a code (same code, E suffix swapped for M) for reliability context. Other dataset families (pep, dec, cbp, ecnbasic, nonemp) publish no margins of error.
`predicates`	No	Filter values keyed by variable code, applied to every geography in the comparison — e.g. {"NAICS2017": "5112"} to rank counties by their software-publisher establishment count in cbp. The business datasets (cbp, ecnbasic, nonemp), pep/charv, and dec/ddhca declare filter dimensions such as industry (NAICS2017/NAICS2022), legal form (LFO), size class (EMPSZES/RCPSZES), tax status (TAXSTAT), operation type (TYPOP), sex (SEX), age (AGE), and population group (POPGROUP). Leaving one unset is not an error: the Census API substitutes its own default, which is the all-categories total on cbp NAICS2017 but a single population group on dec/ddhca POPGROUP and a single sector on ecnbasic NAICS2022 — so a ranking can read like an overall one without being it. Every unset dimension is named in the response notice and its applied default is echoed per row in applied_filters. Code names vary by dataset and vintage — cbp 2023 uses NAICS2017 while nonemp 2023 uses NAICS2022 — so read them from the notice or from census_search_variables. Call census_list_predicate_values for the codes a dimension accepts; NAICS values are standard North American Industry Classification System codes at any depth (51 information, 5112 software publishers).
`geographies`	No	Optional list of specific geographies to include; only these are returned. Prefer full GEOIDs — the level concatenated with its parents, e.g. "53033" for King County WA and "06037" for Los Angeles County CA — which are nationally unique and so work across states. Bare level codes ("033") are also accepted but match that code in every state unless within scopes them to one. A GEOID is easiest taken from the geography_geoid field of a census_query_data or census_compare_geographies row; from census_resolve_geography, concatenate state_fips, then county_fips when it is present, then fips_summary. Entries that match nothing, and bare codes that match more than one state, are named in the response notice.
`within_county`	No	County FIPS to constrain tract or block-group comparisons to a single county within the state specified by within (e.g., "033" for King County). Required when geography_level is "tract" or "block group" and you want county-scoped results. census_resolve_geography returns this as county_fips. Pass "*" to span every county in the state, which is the only way a block-group comparison reaches a whole state. Blank is treated as omitted.
`geography_level`	Yes	The level to compare across (e.g., "state", "county", "tract"). Use census_list_geographies to see valid values for the dataset.

Output Schema

TableJSON Schema

Name	Required	Description
`rows`	No	Geographies sorted by the requested variable. Suppressed values are labeled.
`year`	No	Vintage year queried.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when results were truncated, when geographies entries matched no row, when a bare level code matched more than one state, or when the dataset declares filter dimensions the comparison left unset — how to narrow scope, raise the limit, correct the FIPS codes, or add the predicates that pin what the ranking covers. For an unset dimension it also quotes the label of the default the Census API applied, which is what says whether the ranking is on a total or on one category.
`dataset`	No	Dataset queried.
`truncated`	No	True when totalCount exceeds the limit and results were cut off.
`totalCount`	No	Total number of geographies matched before the limit was applied.
`sortVariable`	No	Variable code used for sorting.

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 19, 2026

TDQS

A4.7/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, and the description adds substantial behavior beyond that: suppressed values are decoded to readable labels, unset predicates use Census-chosen defaults with per-row applied_filters, and unpinned multi-record datasets fail with ambiguous_rows rather than returning duplicate ranks. This covers failure modes and default behavior that the agent would otherwise have to discover at runtime.

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?

At around 350 words the description is long, but every sentence carries a distinct piece of guidance: scope, ranking, suppressed values, predicate defaults, ambiguous_rows, and GEOID construction. It is front-loaded with the core purpose and examples before moving to edge cases, which is appropriate for a complex 11-parameter tool.

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 the tool's complexity – 11 parameters, nested predicates, multiple dataset families, and subtle failure modes – the description covers the critical traps (default predicate categories, ambiguous_rows, bare GEOID ambiguity) and points to sibling tools for valid values. The presence of an output schema covers return-shape details, so nothing essential is left for the agent to guess.

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?

The schema already has exhaustive descriptions for all 11 parameters (100% coverage), so the baseline is 3. The description nonetheless adds practical value by explaining the ACS margin-of-error convention, the MONTH pinning example for pep/charv, and how to construct GEOIDs from census_resolve_geography fields. It does not restate the schema, and the added examples are directly actionable.

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-resource pair ('Compare one or more variables across multiple geographies at the same level'), provides three concrete query examples, and emphasizes sorted/ranked output, which clearly separates it from a plain data retrieval tool. It also states scope behavior ('Omit within to compare all geographies nationally'), making the tool's job unmistakable.

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?

The description gives clear usage contexts: ranking states/counties/tracts, comparing within a state vs nationally, and using named geography sets. It references sibling tools for prerequisites (census_resolve_geography, census_list_predicate_values, census_search_variables), but it does not explicitly say when to prefer census_query_data or when this tool is inappropriate, so exclusions are absent.

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.