Skip to main content
Glama

Census Acs

census_acs
Read-onlyIdempotent

Median home value and median rent for a US ZIP CODE, city, town, county or state, from the American Community Survey, the keyless way to answer "what do homes cost in 33158" or "median home price in Miami-Dade County" at a grain below metro level. Pass the geography the way a person says it: a 5-digit ZIP ("33158"), a place with its state ("Palmetto Bay, FL"), a county ("Miami-Dade County, FL"), or a state ("Florida"); FIPS codes and raw Census "for" syntax also work. Median home value is B25077_001E and median gross rent is B25064_001E (B25003 is tenure counts, not rent); the same call also serves ownership rates, vacancy and any other ACS variable code. Values are 5-year survey estimates, so they describe a period rather than this month's asking prices.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "geography": "33158",
      "variables": "NAME,B25077_001E,B25064_001E"
    },
    "name": "census_acs"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNoSurvey year (default 2022). ACS 5-year estimates available from 2009 onward.
_apiKeyYesCensus API key
geographyYesGeographic level and filter using Census "for" syntax (e.g., "state:06" for California, "county:*" for all counties, "state:*" for all states, "county:037&in=state:06" for LA County).
variablesYesComma-separated variable codes to retrieve (e.g., "NAME,B25001_001E,B25077_001E"). Always include NAME for place names.

Output Schema

NameRequiredDescriptionDefault
yearYesSurvey year queried
resultsYesArray of objects with Census data
geographyYesGeographic filter used
variablesYesVariable codes requested

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "geography": "33158",
      -    "variables": "NAME,B25077_001E,B25064_001E"
      -  },
      -  {
      -    "geography": "Miami-Dade County, FL",
      -    "variables": "NAME,B25077_001E"
      -  },
      -  {
      -    "geography": "Palmetto Bay, FL",
      -    "variables": "NAME,B25077_001E"
      -  },
      -  {
      -    "_apiKey": "your-census-api-key",
      -    "geography": "state:06",
      -    "variables": "NAME,B25001_001E,B25077_001E",
      -    "year": 2022
      -  },
      -  {
      -    "_apiKey": "your-census-api-key",
      -    "geography": "county:037&in=state:06",
      -    "variables": "NAME,B25003_002E,B25003_003E"
      -  },
      -  {
      -    "geography": "us:*",
      -    "variables": "NAME,B25064_001E"
      -  }
      -]New value: +[
      +  {
      +    "geography": "33158",
      +    "variables": "NAME,B25077_001E,B25064_001E"
      +  },
      +  {
      +    "geography": "Miami-Dade County, FL",
      +    "variables": "NAME,B25077_001E"
      +  },
      +  {
      +    "geography": "Palmetto Bay, FL",
      +    "variables": "NAME,B25077_001E"
      +  },
      +  {
      +    "geography": "state:06",
      +    "variables": "NAME,B25001_001E,B25077_001E",
      +    "year": 2022
      +  },
      +  {
      +    "geography": "county:037&in=state:06",
      +    "variables": "NAME,B25003_002E,B25003_003E"
      +  },
      +  {
      +    "geography": "us:*",
      +    "variables": "NAME,B25064_001E"
      +  }
      +]
  2. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "_apiKey": "your-census-api-key",
      -    "geography": "state:06",
      -    "variables": "NAME,B25001_001E,B25077_001E",
      -    "year": 2022
      -  },
      -  {
      -    "_apiKey": "your-census-api-key",
      -    "geography": "county:037&in=state:06",
      -    "variables": "NAME,B25003_002E,B25003_003E"
      -  },
      -  {
      -    "geography": "us:*",
      -    "variables": "NAME,B25064_001E"
      -  }
      -]New value: +[
      +  {
      +    "geography": "33158",
      +    "variables": "NAME,B25077_001E,B25064_001E"
      +  },
      +  {
      +    "geography": "Miami-Dade County, FL",
      +    "variables": "NAME,B25077_001E"
      +  },
      +  {
      +    "geography": "Palmetto Bay, FL",
      +    "variables": "NAME,B25077_001E"
      +  },
      +  {
      +    "_apiKey": "your-census-api-key",
      +    "geography": "state:06",
      +    "variables": "NAME,B25001_001E,B25077_001E",
      +    "year": 2022
      +  },
      +  {
      +    "_apiKey": "your-census-api-key",
      +    "geography": "county:037&in=state:06",
      +    "variables": "NAME,B25003_002E,B25003_003E"
      +  },
      +  {
      +    "geography": "us:*",
      +    "variables": "NAME,B25064_001E"
      +  }
      +]
  3. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "_apiKey": "your-census-api-key",
      -    "geography": "state:06",
      -    "variables": "NAME,B25001_001E,B25077_001E",
      -    "year": 2022
      -  },
      -  {
      -    "_apiKey": "your-census-api-key",
      -    "geography": "county:037&in=state:06",
      -    "variables": "NAME,B25003_002E,B25003_003E"
      -  }
      -]New value: +[
      +  {
      +    "_apiKey": "your-census-api-key",
      +    "geography": "state:06",
      +    "variables": "NAME,B25001_001E,B25077_001E",
      +    "year": 2022
      +  },
      +  {
      +    "_apiKey": "your-census-api-key",
      +    "geography": "county:037&in=state:06",
      +    "variables": "NAME,B25003_002E,B25003_003E"
      +  },
      +  {
      +    "geography": "us:*",
      +    "variables": "NAME,B25064_001E"
      +  }
      +]
  4. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "geography": {
      +      "description": "Geographic filter used",
      +      "type": "string"
      +    },
      +    "results": {
      +      "description": "Array of objects with Census data",
      +      "items": {
      +        "additionalProperties": {
      +          "type": "string"
      +        },
      +        "description": "Census data rows with variable codes as keys",
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "variables": {
      +      "description": "Variable codes requested",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "year": {
      +      "description": "Survey year queried",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "year",
      +    "variables",
      +    "geography",
      +    "results"
      +  ],
      +  "type": "object"
      +}
  5. Changed1 schema field changed
    • addedInput schema / examples
      Added value: +[
      +  {
      +    "_apiKey": "your-census-api-key",
      +    "geography": "state:06",
      +    "variables": "NAME,B25001_001E,B25077_001E",
      +    "year": 2022
      +  },
      +  {
      +    "_apiKey": "your-census-api-key",
      +    "geography": "county:037&in=state:06",
      +    "variables": "NAME,B25003_002E,B25003_003E"
      +  }
      +]
  6. First observed

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so the safety profile needs no restating. The description does add two useful behavioral facts: results are 5-year survey estimates describing a period rather than current asking prices, and B25003 is tenure counts rather than rent, guarding against a common misinterpretation. However, 'the keyless way' sits awkwardly next to a required _apiKey parameter and no rate-limit or pagination behavior is disclosed.

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 lead sentence front-loads what is returned and for which geographies, and every following clause (input formats, variable codes, estimate caveat) carries distinct information. The sentences are long and could be split, and the 'keyless' phrasing is a small distraction, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a rich output schema and full annotation coverage, the description only needs to carry input conventions and caveats, and it does: geography formats, variable code meaning, survey-period semantics. The one hole is the tension between 'keyless' and the required _apiKey parameter, which an agent must resolve by reading the schema.

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 the baseline is 3, but the description genuinely adds meaning: the schema only documents raw Census "for" syntax while the text explains that plain human phrasing like "Palmetto Bay, FL" works and that FIPS codes pass through too. It also decodes the key variable codes (B25077_001E, B25064_001E) and their common confusion with B25003, which the schema does not explain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact measures (median home value, median rent), the source (American Community Survey), and the supported grains (ZIP, city, town, county, state at a grain below metro). It is instantly identifiable, though it does not name a sibling such as census_homeownership to route away from, and 'or any other ACS variable code' broadens the scope in a way that overlaps other census tools.

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?

Two concrete example questions ("what do homes cost in 33158", "median home price in Miami-Dade County") make the intended use case unambiguous, and the accepted geography forms are spelled out. It stops short of stating when a different tool should be used instead, so there is no explicit exclusion or alternative.

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.