Skip to main content
Glama

Resolve Census Geography

census_resolve_geography
Read-only

Resolve a place name, ZIP code, or street address to Census FIPS identifiers. Converts names like "King County, WA", "Seattle, WA", or "Seattle-Tacoma-Bellevue, WA", and ZIPs like "98109", to the codes required by census_query_data and census_compare_geographies. Use before querying when you have a place name rather than raw FIPS codes — state_fips maps to parent_fips and fips_summary maps to geography_fips in downstream tools, and geography_type is itself the geography_level to query at.

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": {
      "name": "<name>"
    },
    "name": "census_resolve_geography"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesPlace name (e.g., "King County, WA", "Seattle, WA", "California"), 5-digit ZIP code (e.g., "98109", resolved to its ZIP Code Tabulation Area), or street address of at most 100 characters (e.g., "1600 Pennsylvania Ave NW, Washington, DC 20500"). Include the state after a comma — its abbreviation or full name, as in "Chatham County, Georgia" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so "Kansas City, MO" and "Kansas City, KS" both reach the MO-KS metro area. Matching ignores case, reads "Saint" and "St." as the same word, and accepts unaccented spellings ("Dona Ana County, NM"). For a statistical area a leading city is enough ("Denver, CO" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city ("Denver-Aurora-Lakewood, CO"). A New York City borough with a New York suffix resolves to the county it is coextensive with when geography_type is "county" or omitted — "Brooklyn, NY" is Kings County, "Manhattan, NY" New York County, "Staten Island, NY" Richmond County. At county subdivision it is the borough's own subdivision; at any other level it is no_match, and at place, economic place, state, tract, or consolidated city the hint names the county. In the twelve states whose towns and townships govern like incorporated places, a town or township resolves to its county subdivision ("Cherry Hill, NJ", "Greenwich, CT"), and a trailing "Township" also reaches a Michigan charter township ("Clinton Township, MI"). "Fairfield County, CT" — or "Fairfield, CT" at geography_type "county" — resolves to Connecticut's county 001 from before 2022, which every vintage through 2021 publishes; the other seven of those eight counties resolve the same way.
county_fipsNoCounty FIPS code to resolve within — 1 to 3 digits, zero-padded here to the 3 the Census stores. A tract name is unique only inside its county, and a town or township name can repeat across a state's counties, so a name matching two counties comes back as ambiguous_name until this is set: take the countyFips of the candidate you want from that error and re-call. Only county, county subdivision, and tract sit within a county, so this restricts resolution to those three levels — pairing it with any other geography_type, or with a street address, is a county_scope_unsupported error rather than a scope quietly dropped. census_query_data takes the same code as its own county_fips.
geography_typeNoGeography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, county subdivision, place, tract, and zip code tabulation area: zip code tabulation area for a 5-digit ZIP or ZIP+4 — the ACS's ZIP-shaped area, not cbp's "zip code" level, which takes the ZIP itself with no resolution — state for a two-letter abbreviation or a spelled-out state name, county when the name contains the word "County" or "Parish", county then place for the word "Borough" (an Alaska borough is a county, a PA or NJ borough a place), tract for the word "Tract", otherwise place (incorporated places and census-designated places together) with a fallback to county, where a census-designated place answers only when no incorporated place or county has the exact name — "Arlington, VA" is Arlington County, and set "place" to reach the Arlington CDP. When the state suffix is one of the twelve states whose towns and townships govern like incorporated places (CT, ME, MA, MI, MN, NH, NJ, NY, PA, RI, VT, WI), county subdivision follows county in that chain: a town or township named exactly the input outranks a CDP of that name and a place that only contains it ("Cherry Hill, NJ" is Cherry Hill township, not Cherry Hill Mall CDP), while a county named exactly it still answers ("Plymouth, MA" is Plymouth County, and the notice names Plymouth town). Elsewhere a county subdivision is a statistical census county division or a township without a place's powers — some, as in Ohio and Illinois, have a government of their own — and is never auto-detected; set "county subdivision" to resolve one in any state. The other four are never auto-detected and must be set explicitly, because their names overlap city names — "metropolitan statistical area/micropolitan statistical area" covers both metro and micro areas and yields a 5-digit code, "combined statistical area" yields a 3-digit code, "consolidated city" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS), and "economic place" yields the 8-digit code ecnbasic 2022 publishes a place under: the 3-digit county it lies in (000 when it spans counties) followed by its 5-digit place code. Economic places are the incorporated places, census-designated places, and county subdivisions the 2022 Economic Census tabulates, plus each county's remainder ("Balance of Adams County, WA"). Setting it explicitly also overrides auto-detection — "New York" auto-detects as the state, so New York City needs "place".

Output Schema

NameRequiredDescriptionDefault
nameNoCanonical name of the resolved geography.
errorNoPresent when the call failed. Absent on success.
noticeNoPresent when the result needs context its fields cannot carry: a New York City borough ("Brooklyn", "The Bronx", "Queens borough") resolved to the county it is coextensive with; a county subdivision with its own government named exactly the input — beside a county auto-detected in one of the twelve town-and-township states, or a census-designated place resolved at geography_type "place" there — named with its county and code, or a statement that the check could not run; a Connecticut county from before 2022, which vintages through 2021 publish in place of the planning regions; or a census tract, which is a 2020 tract that earlier vintages, drawn on earlier tracts, can lack — and in Connecticut sits under its planning region, where vintages through 2021 publish the same code under an earlier county.
place_fipsNo5-digit place FIPS code when the resolved geography is a place — incorporated or census-designated. For an economic place, the place part of its 8-digit code, which is also the place code the 2017 and 2012 ecnbasic vintages take. For a street address, the incorporated place the address sits in (query it at the place level with state_fips as parent_fips); absent when the address is outside every incorporated place, and a census-designated place is never reported for an address.
state_fipsNo2-digit state FIPS code. Use as parent_fips in census_query_data for sub-state queries. Absent for a metropolitan/micropolitan or combined statistical area, which can span several states and needs no parent_fips, and for a zip code tabulation area, whose source layer carries no state.
tract_fipsNo6-digit census tract FIPS code when the resolved geography is a tract — from a street address, or from a tract name. It is a 2020 census tract, which ACS 5-year vintages from 2020 and the 2020 Census files publish; earlier vintages publish earlier tracts, where the code can be missing, and the notice says so.
county_fipsNo3-digit county FIPS code when the resolved geography is a county or sub-county level.
fips_summaryNoPre-formatted FIPS value ready to use as geography_fips in census_query_data (e.g., "033" for King County with state_fips "53" as parent_fips, "42660" for the Seattle-Tacoma-Bellevue metro area with no parent at all, "03363000" for Seattle as an ecnbasic 2022 economic place).
geography_typeNoResolved geography level. Pass this straight through as geography_level in census_query_data and census_compare_geographies.
block_group_fipsNo1-digit block group within tract_fips, for a street address only. Query it as geography_level "block group" with this as geography_fips, alongside parent_fips, county_fips, and tract_fips. geography_type and fips_summary stay at the tract.
census_designated_placeNoPresent (true) when the resolved place or economic place is a census-designated place (CDP): an unincorporated community the Census delineates for statistics, with no municipal government. Its code is queried like an incorporated place's. Absent for an incorporated place and every other level.
county_subdivision_fipsNo5-digit county subdivision FIPS code: the resolved town, township, or other county subdivision (the same code as fips_summary), or for a street address the county subdivision the address sits in — query it at geography_level "county subdivision" with this as geography_fips, state_fips as parent_fips, and county_fips. A Connecticut subdivision carries its planning-region county (110–190), the one vintages from 2022 publish it under; vintages through 2021 publish it under the county from before 2022.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • changedInput schema / properties / county_fips / description
      Previous value: -"County FIPS code to resolve within — 1 to 3 digits, zero-padded here to the 3 the Census stores. A tract name is unique only inside its county, so a bare tract name matching two counties comes back as ambiguous_name until this is set: take the countyFips of the candidate you want from that error and re-call. Only county and tract sit within a county, so this restricts resolution to those two levels — pairing it with any other geography_type, or with a street address, is a county_scope_unsupported error rather than a scope quietly dropped. census_query_data takes the same code as its own county_fips but pads nothing, so hand it the 3-digit county_fips returned here, not the shorter value."New value: +"County FIPS code to resolve within — 1 to 3 digits, zero-padded here to the 3 the Census stores. A tract name is unique only inside its county, and a town or township name can repeat across a state's counties, so a name matching two counties comes back as ambiguous_name until this is set: take the countyFips of the candidate you want from that error and re-call. Only county, county subdivision, and tract sit within a county, so this restricts resolution to those three levels — pairing it with any other geography_type, or with a street address, is a county_scope_unsupported error rather than a scope quietly dropped. census_query_data takes the same code as its own county_fips."
    • changedInput schema / properties / geography_type / description
      Previous value: -"Geography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, place, tract, and zip code tabulation area: zip code tabulation area for a 5-digit ZIP or ZIP+4 — the ACS's ZIP-shaped area, not cbp's \"zip code\" level, which takes the ZIP itself with no resolution — state for a two-letter abbreviation or a spelled-out state name, county when the name contains the word \"County\" or \"Parish\", county then place for the word \"Borough\" (an Alaska borough is a county, a PA or NJ borough a place), tract for the word \"Tract\", otherwise place (incorporated places and census-designated places together) with a fallback to county, where a census-designated place answers only when no incorporated place or county has the exact name — \"Arlington, VA\" is Arlington County, and set \"place\" to reach the Arlington CDP. The other four are never auto-detected and must be set explicitly, because their names overlap city names — \"metropolitan statistical area/micropolitan statistical area\" covers both metro and micro areas and yields a 5-digit code, \"combined statistical area\" yields a 3-digit code, \"consolidated city\" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS), and \"economic place\" yields the 8-digit code ecnbasic 2022 publishes a place under: the 3-digit county it lies in (000 when it spans counties) followed by its 5-digit place code. Economic places are the incorporated places, census-designated places, and county subdivisions the 2022 Economic Census tabulates, plus each county's remainder (\"Balance of Adams County, WA\"). Setting it explicitly also overrides auto-detection — \"New York\" auto-detects as the state, so New York City needs \"place\"."New value: +"Geography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, county subdivision, place, tract, and zip code tabulation area: zip code tabulation area for a 5-digit ZIP or ZIP+4 — the ACS's ZIP-shaped area, not cbp's \"zip code\" level, which takes the ZIP itself with no resolution — state for a two-letter abbreviation or a spelled-out state name, county when the name contains the word \"County\" or \"Parish\", county then place for the word \"Borough\" (an Alaska borough is a county, a PA or NJ borough a place), tract for the word \"Tract\", otherwise place (incorporated places and census-designated places together) with a fallback to county, where a census-designated place answers only when no incorporated place or county has the exact name — \"Arlington, VA\" is Arlington County, and set \"place\" to reach the Arlington CDP. When the state suffix is one of the twelve states whose towns and townships govern like incorporated places (CT, ME, MA, MI, MN, NH, NJ, NY, PA, RI, VT, WI), county subdivision follows county in that chain: a town or township named exactly the input outranks a CDP of that name and a place that only contains it (\"Cherry Hill, NJ\" is Cherry Hill township, not Cherry Hill Mall CDP), while a county named exactly it still answers (\"Plymouth, MA\" is Plymouth County, and the notice names Plymouth town). Elsewhere a county subdivision is a statistical census county division or a township without a place's powers — some, as in Ohio and Illinois, have a government of their own — and is never auto-detected; set \"county subdivision\" to resolve one in any state. The other four are never auto-detected and must be set explicitly, because their names overlap city names — \"metropolitan statistical area/micropolitan statistical area\" covers both metro and micro areas and yields a 5-digit code, \"combined statistical area\" yields a 3-digit code, \"consolidated city\" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS), and \"economic place\" yields the 8-digit code ecnbasic 2022 publishes a place under: the 3-digit county it lies in (000 when it spans counties) followed by its 5-digit place code. Economic places are the incorporated places, census-designated places, and county subdivisions the 2022 Economic Census tabulates, plus each county's remainder (\"Balance of Adams County, WA\"). Setting it explicitly also overrides auto-detection — \"New York\" auto-detects as the state, so New York City needs \"place\"."
    • changedInput schema / properties / geography_type / enum
      Previous value: -[
      -  "state",
      -  "county",
      -  "place",
      -  "tract",
      -  "metropolitan statistical area/micropolitan statistical area",
      -  "combined statistical area",
      -  "consolidated city",
      -  "zip code tabulation area",
      -  "economic place"
      -]New value: +[
      +  "state",
      +  "county",
      +  "county subdivision",
      +  "place",
      +  "tract",
      +  "metropolitan statistical area/micropolitan statistical area",
      +  "combined statistical area",
      +  "consolidated city",
      +  "zip code tabulation area",
      +  "economic place"
      +]
    • changedInput schema / properties / name / description
      Previous value: -"Place name (e.g., \"King County, WA\", \"Seattle, WA\", \"California\"), 5-digit ZIP code (e.g., \"98109\", resolved to its ZIP Code Tabulation Area), or street address (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\"). Include the state after a comma — its abbreviation or full name, as in \"Chatham County, Georgia\" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so \"Kansas City, MO\" and \"Kansas City, KS\" both reach the MO-KS metro area. Matching ignores case, reads \"Saint\" and \"St.\" as the same word, and accepts unaccented spellings (\"Dona Ana County, NM\"). For a statistical area a leading city is enough (\"Denver, CO\" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city (\"Denver-Aurora-Lakewood, CO\"). A New York City borough with a New York suffix resolves to the county it is coextensive with when geography_type is \"county\" or omitted — \"Brooklyn, NY\" is Kings County, \"Manhattan, NY\" New York County, \"Staten Island, NY\" Richmond County. At any other level it is no_match, and at place, economic place, state, tract, or consolidated city the hint names the county."New value: +"Place name (e.g., \"King County, WA\", \"Seattle, WA\", \"California\"), 5-digit ZIP code (e.g., \"98109\", resolved to its ZIP Code Tabulation Area), or street address of at most 100 characters (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\"). Include the state after a comma — its abbreviation or full name, as in \"Chatham County, Georgia\" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so \"Kansas City, MO\" and \"Kansas City, KS\" both reach the MO-KS metro area. Matching ignores case, reads \"Saint\" and \"St.\" as the same word, and accepts unaccented spellings (\"Dona Ana County, NM\"). For a statistical area a leading city is enough (\"Denver, CO\" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city (\"Denver-Aurora-Lakewood, CO\"). A New York City borough with a New York suffix resolves to the county it is coextensive with when geography_type is \"county\" or omitted — \"Brooklyn, NY\" is Kings County, \"Manhattan, NY\" New York County, \"Staten Island, NY\" Richmond County. At county subdivision it is the borough's own subdivision; at any other level it is no_match, and at place, economic place, state, tract, or consolidated city the hint names the county. In the twelve states whose towns and townships govern like incorporated places, a town or township resolves to its county subdivision (\"Cherry Hill, NJ\", \"Greenwich, CT\"), and a trailing \"Township\" also reaches a Michigan charter township (\"Clinton Township, MI\"). \"Fairfield County, CT\" — or \"Fairfield, CT\" at geography_type \"county\" — resolves to Connecticut's county 001 from before 2022, which every vintage through 2021 publishes; the other seven of those eight counties resolve the same way."
    • addedOutput schema / properties / county_subdivision_fips
      Added value: +{
      +  "description": "5-digit county subdivision FIPS code: the resolved town, township, or other county subdivision (the same code as fips_summary), or for a street address the county subdivision the address sits in — query it at geography_level \"county subdivision\" with this as geography_fips, state_fips as parent_fips, and county_fips. A Connecticut subdivision carries its planning-region county (110–190), the one vintages from 2022 publish it under; vintages through 2021 publish it under the county from before 2022.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: Place name not recognized at any geography level tried for it. `ambiguous_name`: Name matched more than one geography. `county_scope_unsupported`: county_fips was combined with a street address, or with a geography_type — set or auto-detected — that does not sit within a county. `resolution_unavailable`: Geography resolution endpoint was unreachable. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_match`: Place name not recognized at any geography level tried for it. `ambiguous_name`: Name matched more than one geography. `county_scope_unsupported`: county_fips was combined with a street address, or with a geography_type — set or auto-detected — that does not sit within a county. `address_rejected`: The Census Geocoder rejected the street address as sent — one longer than 100 characters, for one — and the error carries the geocoder's own statement of why. `resolution_unavailable`: TIGERweb or the Census Geocoder failed with an HTTP error, could not be reached, or did not answer in time on every attempt or within the call's 50-second upstream budget, or answered with a page or an error in place of data. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_match",
      -  "ambiguous_name",
      -  "county_scope_unsupported",
      -  "resolution_unavailable"
      -]New value: +[
      +  "no_match",
      +  "ambiguous_name",
      +  "county_scope_unsupported",
      +  "address_rejected",
      +  "resolution_unavailable"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Present when the name was a New York City borough (\"Brooklyn\", \"The Bronx\", \"Queens borough\") resolved to the county it is coextensive with."New value: +"Present when the result needs context its fields cannot carry: a New York City borough (\"Brooklyn\", \"The Bronx\", \"Queens borough\") resolved to the county it is coextensive with; a county subdivision with its own government named exactly the input — beside a county auto-detected in one of the twelve town-and-township states, or a census-designated place resolved at geography_type \"place\" there — named with its county and code, or a statement that the check could not run; a Connecticut county from before 2022, which vintages through 2021 publish in place of the planning regions; or a census tract, which is a 2020 tract that earlier vintages, drawn on earlier tracts, can lack — and in Connecticut sits under its planning region, where vintages through 2021 publish the same code under an earlier county."
    • changedOutput schema / properties / tract_fips / description
      Previous value: -"6-digit census tract FIPS code when the resolved geography is a tract — from a street address, or from a tract name."New value: +"6-digit census tract FIPS code when the resolved geography is a tract — from a street address, or from a tract name. It is a 2020 census tract, which ACS 5-year vintages from 2020 and the 2020 Census files publish; earlier vintages publish earlier tracts, where the code can be missing, and the notice says so."
  2. Changed2 schema fields changed
    • changedInput schema / properties / name / description
      Previous value: -"Place name (e.g., \"King County, WA\", \"Seattle, WA\", \"California\"), 5-digit ZIP code (e.g., \"98109\", resolved to its ZIP Code Tabulation Area), or street address (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\"). Include the state after a comma — its abbreviation or full name, as in \"Chatham County, Georgia\" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so \"Kansas City, MO\" and \"Kansas City, KS\" both reach the MO-KS metro area. Matching ignores case, reads \"Saint\" and \"St.\" as the same word, and accepts unaccented spellings (\"Dona Ana County, NM\"). For a statistical area a leading city is enough (\"Denver, CO\" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city (\"Denver-Aurora-Lakewood, CO\")."New value: +"Place name (e.g., \"King County, WA\", \"Seattle, WA\", \"California\"), 5-digit ZIP code (e.g., \"98109\", resolved to its ZIP Code Tabulation Area), or street address (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\"). Include the state after a comma — its abbreviation or full name, as in \"Chatham County, Georgia\" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so \"Kansas City, MO\" and \"Kansas City, KS\" both reach the MO-KS metro area. Matching ignores case, reads \"Saint\" and \"St.\" as the same word, and accepts unaccented spellings (\"Dona Ana County, NM\"). For a statistical area a leading city is enough (\"Denver, CO\" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city (\"Denver-Aurora-Lakewood, CO\"). A New York City borough with a New York suffix resolves to the county it is coextensive with when geography_type is \"county\" or omitted — \"Brooklyn, NY\" is Kings County, \"Manhattan, NY\" New York County, \"Staten Island, NY\" Richmond County. At any other level it is no_match, and at place, economic place, state, tract, or consolidated city the hint names the county."
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Present when the name was a New York City borough (\"Brooklyn\", \"The Bronx\", \"Queens borough\") resolved to the county it is coextensive with.",
      +  "type": "string"
      +}
  3. Changed8 schema fields changed
    • changedInput schema / properties / geography_type / description
      Previous value: -"Geography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, place, and tract: state for a two-letter abbreviation or a spelled-out state name, county when the name contains \"County\"/\"Borough\"/\"Parish\", tract when it contains \"Tract\", otherwise place with a fallback to county. The other three are never auto-detected and must be set explicitly, because their names overlap city names — \"metropolitan statistical area/micropolitan statistical area\" covers both metro and micro areas and yields a 5-digit code, \"combined statistical area\" yields a 3-digit code, and \"consolidated city\" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS). Setting it explicitly also overrides auto-detection — \"New York\" auto-detects as the state, so New York City needs \"place\"."New value: +"Geography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, place, tract, and zip code tabulation area: zip code tabulation area for a 5-digit ZIP or ZIP+4 — the ACS's ZIP-shaped area, not cbp's \"zip code\" level, which takes the ZIP itself with no resolution — state for a two-letter abbreviation or a spelled-out state name, county when the name contains the word \"County\" or \"Parish\", county then place for the word \"Borough\" (an Alaska borough is a county, a PA or NJ borough a place), tract for the word \"Tract\", otherwise place (incorporated places and census-designated places together) with a fallback to county, where a census-designated place answers only when no incorporated place or county has the exact name — \"Arlington, VA\" is Arlington County, and set \"place\" to reach the Arlington CDP. The other four are never auto-detected and must be set explicitly, because their names overlap city names — \"metropolitan statistical area/micropolitan statistical area\" covers both metro and micro areas and yields a 5-digit code, \"combined statistical area\" yields a 3-digit code, \"consolidated city\" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS), and \"economic place\" yields the 8-digit code ecnbasic 2022 publishes a place under: the 3-digit county it lies in (000 when it spans counties) followed by its 5-digit place code. Economic places are the incorporated places, census-designated places, and county subdivisions the 2022 Economic Census tabulates, plus each county's remainder (\"Balance of Adams County, WA\"). Setting it explicitly also overrides auto-detection — \"New York\" auto-detects as the state, so New York City needs \"place\"."
    • changedInput schema / properties / geography_type / enum
      Previous value: -[
      -  "state",
      -  "county",
      -  "place",
      -  "tract",
      -  "metropolitan statistical area/micropolitan statistical area",
      -  "combined statistical area",
      -  "consolidated city"
      -]New value: +[
      +  "state",
      +  "county",
      +  "place",
      +  "tract",
      +  "metropolitan statistical area/micropolitan statistical area",
      +  "combined statistical area",
      +  "consolidated city",
      +  "zip code tabulation area",
      +  "economic place"
      +]
    • changedInput schema / properties / name / description
      Previous value: -"Place name (e.g., \"King County, WA\", \"Seattle, WA\", \"California\") or street address (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\"). Include the state abbreviation to disambiguate places with common names — it narrows a statistical area as well, matching any state the area spans, so \"Kansas City, MO\" and \"Kansas City, KS\" both reach the MO-KS metro area. For a statistical area, the name is the full hyphenated one the Census publishes (\"Seattle-Tacoma-Bellevue, WA\" for the metro area, \"Seattle-Tacoma, WA\" for the combined one) — a single city name matches it too when only one area contains that city."New value: +"Place name (e.g., \"King County, WA\", \"Seattle, WA\", \"California\"), 5-digit ZIP code (e.g., \"98109\", resolved to its ZIP Code Tabulation Area), or street address (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\"). Include the state after a comma — its abbreviation or full name, as in \"Chatham County, Georgia\" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so \"Kansas City, MO\" and \"Kansas City, KS\" both reach the MO-KS metro area. Matching ignores case, reads \"Saint\" and \"St.\" as the same word, and accepts unaccented spellings (\"Dona Ana County, NM\"). For a statistical area a leading city is enough (\"Denver, CO\" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city (\"Denver-Aurora-Lakewood, CO\")."
    • addedOutput schema / properties / block_group_fips
      Added value: +{
      +  "description": "1-digit block group within tract_fips, for a street address only. Query it as geography_level \"block group\" with this as geography_fips, alongside parent_fips, county_fips, and tract_fips. geography_type and fips_summary stay at the tract.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / census_designated_place
      Added value: +{
      +  "const": true,
      +  "description": "Present (true) when the resolved place or economic place is a census-designated place (CDP): an unincorporated community the Census delineates for statistics, with no municipal government. Its code is queried like an incorporated place's. Absent for an incorporated place and every other level.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / fips_summary / description
      Previous value: -"Pre-formatted FIPS value ready to use as geography_fips in census_query_data (e.g., \"033\" for King County with state_fips \"53\" as parent_fips, \"42660\" for the Seattle-Tacoma-Bellevue metro area with no parent at all)."New value: +"Pre-formatted FIPS value ready to use as geography_fips in census_query_data (e.g., \"033\" for King County with state_fips \"53\" as parent_fips, \"42660\" for the Seattle-Tacoma-Bellevue metro area with no parent at all, \"03363000\" for Seattle as an ecnbasic 2022 economic place)."
    • changedOutput schema / properties / place_fips / description
      Previous value: -"Place FIPS code when the resolved geography is an incorporated place."New value: +"5-digit place FIPS code when the resolved geography is a place — incorporated or census-designated. For an economic place, the place part of its 8-digit code, which is also the place code the 2017 and 2012 ecnbasic vintages take. For a street address, the incorporated place the address sits in (query it at the place level with state_fips as parent_fips); absent when the address is outside every incorporated place, and a census-designated place is never reported for an address."
    • changedOutput schema / properties / state_fips / description
      Previous value: -"2-digit state FIPS code. Use as parent_fips in census_query_data for sub-state queries. Absent for a metropolitan/micropolitan or combined statistical area, which can span several states and needs no parent_fips."New value: +"2-digit state FIPS code. Use as parent_fips in census_query_data for sub-state queries. Absent for a metropolitan/micropolitan or combined statistical area, which can span several states and needs no parent_fips, and for a zip code tabulation area, whose source layer carries no state."
  4. First observed

TDQS

A4.7/5.0
Behavior4/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 genuine behavioral context beyond that: it says resolution can fail with ambiguity and must be re-called with a county, and it names specific downstream identifiers. It does not itself surface the error codes described in the schema (ambiguous_name, county_scope_unsupported), so the behavioral picture is completed mostly by the parameter docs rather than the description body.

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?

Three sentences, front-loaded with the core verb-and-resource statement, then the examples, then the downstream contract. No filler or restatement of the title; the density of the third sentence is justified by three distinct field mappings.

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?

An output schema exists, so return values need not be described, and the heavy resolution rules (auto-detection chain, boroughs, townships, economic places) live in the schema where they belong. For a read-only resolver with three parameters, the description covers purpose, invocation timing, and chaining completely.

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 description coverage is 100%, so the baseline is 3, but the description earns above baseline by explaining what each resolved field becomes downstream (parent_fips, geography_fips, geography_level). It does not restate the name/county_fips/geography_type syntax, appropriately deferring to the rich per-parameter schema text.

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 (Resolve) and the input resources (place name, ZIP code, street address) mapped to a specific output (Census FIPS identifiers). It also names the two sibling tools that consume the result (census_query_data and census_compare_geographies), making it distinguishable from them without opening a schema.

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 before querying when you have a place name rather than raw FIPS codes," which cleanly separates this tool from census_query_data (which wants FIPS). It goes further and documents the field mapping across the boundary (state_fips to parent_fips, fips_summary to geography_fips, geography_type to geography_level), so the agent knows both when to call it and how to chain it.

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.