Skip to main content
Glama

Zip-Codes.com Location Intelligence: Spatial Analysis, Districts & 14+ Years of Demographics

by com.zip-codes
OverviewDiscussionsAdmin

ZIP Code lookup

zip_lookup
Read-onlyIdempotent

The full record for a postal code — the main location-intelligence tool. Takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair, and returns the city, state or province, county, whether it spans more than one county, area codes, elevation, metro area and postal details (metro.msa and metro.pmsa are legacy 1999 definitions; the current metro area, the CBSA, comes with census). A ZIP+4 also returns its delivery-segment street ranges, and coordinates reverse-geocode to the code containing the point. Optional enrichments add timezone, census geography, congressional and state legislative districts (for the current year or any TIGER/Line year served), school districts, demographics, Medicare geography and American Community Survey estimates for every release served, all in one schema per year; for Canadian codes, Statistics Canada geography and federal electoral districts (statcan). Use quick_zip instead when only the code and its place are needed — same inputs, about half the payload, no enrichments beyond timezone. Without an API key the core identity fields are returned and everything else is withheld, with each withheld path named.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeYesA US ZIP Code, ZIP+4, Canadian FSA, or Canadian postal code. For example 90210, 90210-1234, M5V, or M5V 2T6.
includeNoEnrichments, spelled as the REST API's /v2/zip include flags. Each multiplies the credit cost: base times (1 + number of enrichments). census, cd (congressional district) and state_leg are US Census Bureau data; census_YYYY, cd_YYYY, state_leg_YYYY add boundaries as of a TIGER/Line year (the bare flag answers under `current`, other years under their own key). statcan is Canada only: Statistics Canada geography for a Canadian FSA or postal code, federal electoral districts included, under `statcan` (statcan_YYYY for a census year; census or cd on a Canadian code is answered as statcan). acs_PROFILE is the current American Community Survey release, acs_PROFILE_YYYY an earlier one; every ACS year has the SAME FIELD PATHS, so values compare across years directly. Accepted: timezone, census, cd, state_leg, school_district, demographics, medicare, statcan, acs_demographic, acs_social, acs_economic, acs_housing; statcan_YYYY for YYYY 2011, 2016, 2021; census_YYYY, cd_YYYY, state_leg_YYYY for YYYY 2010-2025; acs_demographic_YYYY, acs_social_YYYY, acs_economic_YYYY, acs_housing_YYYY for YYYY 2011-2024. A bare flag is its newest year.
acs_yearsNoAlias, kept for clients that learned it before include took year flags: ACS release years for the bare acs_ profiles in include (acs_social with acs_years [2015, 2024] is acs_social_2015 plus acs_social). Prefer the year flags in include. Every year has the SAME FIELD PATHS, and the answer comes back keyed by year. At most 16 profile-years per call. 2011 to 2024 (2024 is the current release).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly/openWorld/idempotent, so the safety profile is covered. The description adds genuinely non-structured behavior: credit cost scaling with enrichment count, unauthenticated withholding with each withheld path named, and the legacy 1999 metro.msa/pmsa caveat. It stops short of describing pagination/response shape, but does not need to.

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 purpose and the quick_zip alternative, then flows into return contents and caveats. One dense paragraph, and the metro.msa/pmsa legacy aside is a mild digression, but nearly every clause carries decision-relevant 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?

With no output schema, the description must carry the return contract, and it does: city/state/county, multi-county flag, area codes, elevation, metro, postal details, ZIP+4 street ranges, reverse-geocode behavior, and per-enrichment payloads. Nothing an agent needs to call it correctly is missing.

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 schema already documents syntax and accepted flags. The description still adds value the schema lacks by explaining what each enrichment family returns (census geography, TIGER/Line-year boundaries, ACS comparability across years) and framing the cost model. Baseline 3 is exceeded but it is not a full substitute for schema detail.

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+resource ('full record for a postal code') and enumerates the accepted input forms (ZIP, ZIP+4, Canadian FSA/postal code, lat/long). It explicitly differentiates from the sibling quick_zip, so an agent can choose between them without opening either 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?

Provides an explicit routing rule: 'Use quick_zip instead when only the code and its place are needed — same inputs, about half the payload, no enrichments beyond timezone.' It also states the API-key degradation path, covering the when-not-to-expect-full-results case.

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

All Zip-Codes.com Location Intelligence: Spatial Analysis, Districts & 14+ Years of Demographics 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