Skip to main content
Glama

Census

by io.github.pipeworx-io
OverviewDiscussionsAdmin

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.

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

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait: values are 5-year survey estimates describing a period, not current asking prices. That is meaningful context beyond the annotations.

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?

Front-loaded with the core purpose and the primary geography forms, and every sentence carries information (variable codes, temporal caveat, syntax). It is dense and slightly long, but there is little waste.

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?

With an output schema present, return values need not be described, and annotations carry the safety profile. The description covers geography syntax, variable-code semantics, the temporal nature of estimates, and the year range, leaving nothing an agent needs in order to call it correctly.

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 adds real meaning: it maps geography formats (ZIP, place+state, county+state, state, FIPS, raw 'for' syntax) to human phrasing and decodes variable codes (B25077_001E = median home value, B25064_001E = median rent, with the B25003 warning). This exceeds what the schema descriptions convey.

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 resource (median home value and median rent from the American Community Survey) plus the supported geographies and the grain (below metro level). This clearly distinguishes it from siblings like census_population, census_homeownership, and census_housing_starts, which cover other ACS dimensions.

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?

Frames concrete use cases ('what do homes cost in 33158', 'median home price in Miami-Dade County') and the accepted geography forms, giving an agent clear context for selection. It stops short of explicitly naming and excluding sibling alternatives for the same question, so it is strong rather than exhaustive.

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

All Census toolsInspect
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.

Resources