Validate & geocode a US address; enrich with demographics, districts, counties, schools & much more.
Scored across 11 tools
Most tools have clearly distinct purposes (reference data, distance, radius search, address validation, fuzzy resolver, stats). The one real overlap is quick_zip vs zip_lookup, which take identical inputs and return overlapping data, though the descriptions work hard to draw the boundary (payload size, available enrichments). The cluster of reference/metadata tools (about_data, city_name_rules, county_reference, metro_area_reference, zip_facts) is dense but each targets a different dataset.
All names are consistently snake_case and readable. They mix noun-style reference names (county_reference, metro_area_reference, city_name_rules) with action-style names (validate_address, suggest_places, radius_search) and bare nouns (distance, quick_zip, zip_facts), so there is no single verb_noun pattern, but the convention is stable and predictable enough to navigate.
Eleven tools is well-scoped for a rich location-intelligence server spanning lookup, reverse geocoding, proximity search, distance, validation, resolution, references and stats. Each tool earns its place and none feels redundant beyond the documented quick_zip/zip_lookup pairing.
Coverage is broad: forward/reverse lookup, radius search, distance, address validation with appendable enrichments, a fuzzy resolver, reference datasets and aggregate stats. The main noted gap is that address validation is US-only with no Canadian counterpart, and bulk/batch operations are absent, but agents can work around both.
Where this server's data comes from: for each dataset the authority behind it, the edition served where the source publishes editions (TIGER/Line, ACS, ZCTA), how often a new release is taken, and a ready-made citation string. Costs nothing and needs no key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds genuinely new context beyond them: no cost and no API key required. It stops short of describing payload size or exact return shape, but for a metadata-only read that is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that enumerates the returned fields and then appends the no-cost/no-key clause. It is dense with a parenthetical list but every clause carries information; nothing is padding, though the sentence is long for one breath.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no input parameters and no output schema, the description carries the full burden of explaining the return value, and it does so by enumerating each field the agent will receive. Nothing needed to select or invoke this zero-argument read tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies the call is parameter-free by framing the output entirely in terms of what is returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is highly specific about what the tool returns: dataset provenance (authority), edition served (TIGER/Line, ACS, ZCTA), release cadence, and a ready-made citation string. That is far beyond a tautology and clearly distinct from the geographic lookup siblings, though it uses no explicit verb and never names a sibling, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent infers it should call this when it needs to attribute or cite the data. 'Costs nothing and needs no key' signals it is safe to call liberally, but there is no explicit when-to-use framing, no conditions, and no reference to alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How USPS names a ZIP Code, and which of those names may be used on mail. Each ZIP Code has exactly one preferred city name plus alternates, and some alternates are NOT valid for addressing — for 08088 NJ, SHAMONG is valid while SHAMONG TOWNSHIP is not. Returns the rules, the counts and a worked example. Costs nothing and needs no key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and openWorld=false, so the bar is lower. The description adds genuinely useful context beyond them: it is free, requires no API key, and returns rules plus counts plus a worked example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: what it is, the key nuance (invalid alternates), and the concrete SHAMONG example. The example earns its place by making the concept unambiguous, and the return/cost facts are front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no input params and no output schema, the description must explain what comes back, and it does (rules, counts, worked example). The only small gap is that it doesn't indicate the response format (structured vs prose), which an agent might want to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema carries no semantics to explain and the baseline is 4. The description correctly avoids inventing parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific subject (how USPS names a ZIP Code and which names are valid for mail) and what it returns (rules, counts, worked example). It is clearly a rules/reference tool rather than a data lookup like zip_lookup or zip_facts, though the differentiation from those siblings is left implicit rather than named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (deciding whether a city name is mailable, e.g. SHAMONG vs SHAMONG TOWNSHIP) but never states when to call this versus zip_lookup, validate_address, or zip_facts, and gives no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
US counties and county equivalents — all 3,235 of them — with their Census and USPS names, which disagree for over a hundred, plus ANSI code, legal type, land and water area, and USPS delivery footprint. Filter by state to get every county in that state: without a filter only the first 25 are returned, and they are FIPS-ordered, so an unfiltered call answers with Alabama rather than with whatever was asked about. Costs nothing and needs no key.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Cap the number of counties returned. Defaults to 25 when no state is given, or to all of them when one is. | |
| state | No | Two-letter US state or territory code. Returns EVERY county in that state, so no limit is needed — Texas is the largest at 254. Omit to browse all states. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, and closed-world behavior, so the bar is lower. The description adds genuinely new operational context: no cost, no API key required, and the FIPS-ordering/pagination default that shapes results. It does not describe the response envelope, but for a read-only reference tool this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense paragraph that front-loads the contents, then the filtering caveat. Every clause carries information, though the sentence is long and could be broken for faster scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return content, and it does: it lists the fields returned and warns about the default 25-row, FIPS-ordered result. An agent has everything needed to call it correctly and interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters already document their defaults, including the state-vs-no-state limit behavior. The description largely restates those defaults, adding only the Texas-at-254 scale detail. Baseline 3 is correct when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (US counties and county equivalents, all 3,235) and enumerates the attributes returned (Census/USPS names, ANSI code, legal type, area, delivery footprint). This is clearly distinguishable from siblings like city_name_rules, metro_area_reference, and zip_facts, which cover different geographies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit conditional guidance: filter by state to get every county, and warns that an unfiltered call returns only the first 25 in FIPS order, so it answers with Alabama rather than what was asked about. That is a real when-to-use/when-not distinction. It stops short of naming a sibling alternative for other geographic lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Distance between two places, in miles and kilometres, plus the compass bearing from the first to the second. Each end takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair, and the two ends can be different kinds — a US ZIP to a Canadian postal code works, and so does a code to a coordinate. Time zone for both ends is included. This is a straight-line distance, not a driving route. Without an API key the distance itself is returned and the geography behind it is withheld.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination, in any of the same forms as the origin. | |
| from | Yes | Origin: a ZIP Code, ZIP+4, Canadian FSA or postal code, or latitude,longitude. For example 90210, M5V 2T6, or 34.10,-118.41. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the description's added value is the straight-line-vs-driving-route caveat and the explicit API-key degradation behavior (distance returned but underlying geography withheld). That auth/behavior disclosure goes beyond the structured fields, though error handling for invalid codes is not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with what the tool returns; input forms, the straight-line caveat, and the API-key caveat each follow in logical order. No sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-value burden and does so: distance in both unit systems, bearing, time zones for both ends, and what is withheld without an API key. Nothing an agent needs in order to call and interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents 'from' and 'to' with examples, setting the baseline at 3. The description earns an extra point by clarifying a rule the schema does not state — the two ends may be of different kinds (US ZIP to Canadian postal code, code to coordinate) — which prevents a reasonable misreading of 'same forms as the origin.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact computation (straight-line distance in miles and kilometres plus compass bearing between two locations) and the units, so an agent knows precisely what it gets back. This distinguishes it from reference siblings like zip_lookup or validate_address, and the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes context (point-to-point distance, not a driving route) and enumerates the accepted input forms, including that the two ends may be different kinds. However, it never says when to choose this over radius_search or suggest_places, so the routing guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
US metropolitan and micropolitan statistical areas (CBSAs) — all 935. Of those only 393 are metropolitan; the rest are micropolitan and are NOT metro areas, so do not treat a CBSA count as a metro count. Each carries its divisions, parent combined area, land area and delivery footprint, plus the CMS Medicare labor market area, which is a DIFFERENT geography that shares the same code space. Filter by state to get every area in that state: without a filter only the first 25 are returned, alphabetically, so an unfiltered call answers with Aberdeen. Costs nothing and needs no key.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Cap the number of areas returned. Defaults to 25 when no state is given, or to all areas in the state when one is. | |
| state | No | Two-letter US state or territory code. Returns every area that includes that state — an area can span several, so it is matched against the area's whole state list. Omit to browse all states. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false). The description adds real context beyond them: no API key required, no cost, 25-row default truncation, and the caveat that the CMS Medicare labor market area is a different geography sharing the same code space.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the resource and its scope caveat, and every clause carries information. The single dense paragraph packs several distinct concepts together, which slightly hurts scannability but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers scope, defaults, truncation behavior, cost/auth, geographic caveats, and the kind of attributes returned (divisions, combined area, land area, delivery footprint). With no output schema, this is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes further by framing why the state filter works the way it does (an area spans several states, so it matches the whole state list) and by tying the unfiltered default to a concrete example (Aberdeen).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (US metropolitan and micropolitan statistical areas / CBSAs) with the distinguishing fact that only 393 of 935 are metropolitan. This clearly separates it from siblings like county_reference and zip_lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit operational guidance: filter by state to get every area in that state, and warns that an unfiltered call returns only the first 25 alphabetically. It also warns not to treat a CBSA count as a metro count. It stops short of naming an alternative sibling tool for related lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The fast, small answer for a postal code. Takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair, and returns the code's city, state or province, county, and whether it spans more than one county. Given a ZIP+4 it also returns the street ranges making up that delivery segment; given coordinates it reverse-geocodes to the code containing the point. zip_lookup accepts exactly the same inputs and returns the same ZIP+4 detail — choose this one when the answer only needs to be the code and its place, because the payload is about half the size and only the timezone enrichment is available here. Use zip_lookup for census, demographic, district or American Community Survey enrichments.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | A US ZIP Code, ZIP+4, Canadian FSA, Canadian postal code, or a latitude,longitude pair. For example 90210, 90210-1234, M5V, M5V 2T6, or 34.10,-118.41. | |
| include | No | Enrichments to add. Only timezone is available on this tool; use zip_lookup for census, district, demographic and ACS enrichments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds substantive behavior beyond them: the fields returned for each input class, that ZIP+4 yields street ranges, that coordinates trigger reverse geocoding, and the payload-size and enrichment-scope limits relative to zip_lookup. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and the smallest viable framing, then the input/output contract, then the sibling routing. Dense but every clause carries information; the only near-filler is the lead phrase 'The fast, small answer for a postal code.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully carries the return-value burden by naming city, state/province, county, multi-county flag, ZIP+4 street ranges, and reverse-geocoded results. It also states the enrichment limitation, leaving nothing an agent needs before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 earns extra: it restates the accepted code formats in context and clarifies that 'include' can only carry timezone here, directing other enrichments to zip_lookup. That is real meaning beyond the schema's terse field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Takes a US ZIP Code... returns the code's city, state or province, county') and enumerates every accepted input form. It explicitly distinguishes itself from the sibling zip_lookup, so an agent can choose 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the selection condition outright: 'choose this one when the answer only needs to be the code and its place, because the payload is about half the size and only the timezone enrichment is available here,' then names where to go instead ('Use zip_lookup for census, demographic, district or American Community Survey enrichments'). Both the when and the when-not are explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find every US ZIP Code and Canadian postal area within a radius of a centre point, with the distance to each. The centre takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair; a ZIP+4 searches from its parent ZIP, and coordinates are used as the point itself, so the centre comes back with no code. Centroid mode measures centre to centre and reaches 500 miles; spatial mode intersects real boundaries, reports how much of each area falls inside, and reaches 250 miles. Set a minimum radius to search a ring rather than a circle. summary.total_count is the number of matches returned; when the list is cut, summary.total_available is the number in the radius and a notice says so. ACS statistics always cover the whole radius. They are aggregates of the ZIP Codes' estimates: est and pct only, with no margin of error or Census column; for one ZIP Code's estimate with its margin of error, use zip_lookup. timezone and ACS come back with the search itself; only census and district data need zip_lookup per ZIP. Without an API key the count and a sample of matches are returned and the rest is withheld; free-tier keys are capped at 100 miles centroid and 50 spatial.
| Name | Required | Description | Default |
|---|---|---|---|
| max | Yes | Radius in miles, as a number or a string. Up to 500 in centroid mode or 250 in spatial mode; exceeding the cap is an error rather than being reduced. May also be 'auto' to pick a radius from local population density, or 'auto-commute' to use commuting patterns where available. | |
| min | No | Minimum radius in miles, to exclude the middle and search a ring. Must be less than max. Defaults to 0. | |
| code | Yes | Centre point: a US ZIP Code, ZIP+4, Canadian FSA or postal code, or a latitude,longitude pair. | |
| mode | No | How to measure. centroid measures centre to centre and is the default when omitted; spatial intersects actual boundaries and adds how much of each area lies inside, at a lower maximum radius. | |
| limit | No | Maximum number of matches to return, up to 100, which is also the default. A larger value is reduced to 100 and the result says so in notices. When the list is cut, summary.total_available is the number of matches in the radius (summary.total_count is the number returned) and a RESULTS_CAPPED notice says so; to see matches beyond the first 100, narrow the radius or raise `min` to step outwards in bands. | |
| include | No | Enrichments, spelled as the REST API's /v2/radius include flags; each multiplies the credit cost. timezone lands on each match. acs_PROFILE (current release) and acs_PROFILE_YYYY return aggregate statistics across the whole result set, with the same field paths every year. Census and district enrichments are not available here; use zip_lookup. Accepted: timezone, acs_demographic, acs_social, acs_economic, acs_housing; acs_demographic_YYYY, acs_social_YYYY, acs_economic_YYYY, acs_housing_YYYY for YYYY 2011-2024. A bare flag is its newest year. | |
| acs_years | No | Alias, 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] is acs_social_2015). Prefer the year flags in include. At most 16 profile-years per call. 2011 to 2024 (2024 is the current release). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/idempotent/openWorld; the description adds the substantive behavior: radius caps (500 centroid, 250 spatial), per-flag credit multiplication, no-API-key behavior (count plus sample, rest withheld), free-tier caps (100/50 miles), RESULTS_CAPPED notices, and the total_count vs total_available distinction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and behaviourally rich, but it is very long and re-states much of what the already-exhaustive schema descriptions cover (mode, limit cap, include flags, acs_years alias), so a meaningful share of the text is redundant rather than additive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 7 parameters, the description still explains return semantics (summary.total_count/total_available, notices, timezone and ACS arriving with the search, ACS aggregates covering the whole radius) and the degraded no-key response, so an agent has what it needs to call and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 genuine meaning beyond the schema: a ZIP+4 searches from its parent ZIP, coordinates are the point itself so no centre code is returned, and ACS flags aggregate the whole radius with est/pct only (no margin of error).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource+scope: 'Find every US ZIP Code and Canadian postal area within a radius of a centre point, with the distance to each.' It also names the sibling it is not (zip_lookup) for single-ZIP estimates, so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes to alternatives in both directions: use zip_lookup for one ZIP's estimate with margin of error, and for census/district enrichments that are unavailable here. It also gives selection criteria for centroid vs spatial mode, min-radius ring searching, and how to step beyond the 100-match cap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for a place by partial name, misspelled name, or partial code — the resolver that turns what a person typed into something the other tools can look up. Fuzzy matching is built in: "beverley hills" finds Beverly Hills, "san fransisco" finds San Francisco, and a partial code like "902" finds the ZIP Codes starting with it. Matches US ZIP Codes, cities, USPS city names, counties, metropolitan areas, states, school districts, Canadian FSAs and Canadian postal codes, ranked, with the total number of matches. Reach for this FIRST when the place is vague, misspelled or partial, then pass the resolved code to zip_lookup, radius_search or distance. Restrict the kinds of place with types, or bias results towards a location with near. Coverage is broad rather than deep — it returns names and codes, not the full record.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | What the user typed. At least one character, at most 200. | |
| near | No | Bias results towards somewhere. Accepts 'latitude,longitude', a 5-digit ZIP Code, a 3-character Canadian FSA, or a two-letter state or province abbreviation. | |
| limit | No | How many results to return. Defaults to 10; free-tier and demo callers are capped at 15, paid keys reach 500. With a key the credit cost follows the requested limit (up to 15: 1 credit; 50: 2; 150: 3; 500: 5), whether or not anything matches; demo calls are not charged. | |
| state | No | Restrict to one US state or Canadian province, as a two-letter abbreviation such as CA, NY or ON. | |
| types | No | Restrict to these kinds of place. Omit to search all of them. | |
| country | No | Restrict to one country. Omit to search both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful behavior — built-in fuzzy matching with concrete examples, ranked results with a total count, and the "names and codes, not the full record" coverage caveat — but says nothing about pagination or result ordering details beyond "ranked."
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then the fuzzy-matching examples, then the routing guidance. Five sentences that mostly earn their place, though the types/near sentence partially duplicates the schema and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by describing the return shape (ranked matches with a total count, names and codes only, no full records). Combined with explicit routing to downstream tools, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so q, near, limit, state, types and country are all already documented, including the cost tiers and enum values. The description's mentions of types and near largely restate the schema; its only added semantic value is characterizing what q accepts (misspellings, partial codes) and the ranked output shape.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and resource (place) with the exact scope: partial name, misspelled name, or partial code. It explicitly frames itself as the resolver feeding zip_lookup, radius_search and distance, so it is unmistakable next to its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Reach for this FIRST when the place is vague, misspelled or partial, then pass the resolved code to zip_lookup, radius_search or distance" gives an explicit ordering plus named downstream alternatives. It also covers the when-not case implicitly by stating coverage is broad rather than deep.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate and standardise a US street address and return its ZIP+4. US ONLY — unlike the postal-code tools, this does not cover Canada. Send the address on one line in mailing order: number and street, then any unit (APT 4, STE 900, #9), then city, state and ZIP. It tolerates ordinary slips (a misspelling, a missing ZIP, state or directional), but it is not a puzzle to solve: a unit placed after the city or ZIP ("Pensacola FL #9") is ambiguous, a unit or a floor. Send what the user gave you, in proper order, once. If it does not match, report that; do not keep trying rewrites. Returns the address in USPS standard form split into its parts, the 5-digit ZIP and the +4 add-on, a confidence level of high, medium or low (low: the +4 may be withheld), and the county, carrier route, congressional district and census block group for the match, all for one credit. include appends more, one credit each: coordinates, the census geographies the address sits inside, its congressional and state legislative districts (now or as of any TIGER/Line year served), its school district, its time zone, and American Community Survey profiles for its census tract. The congressional district already in details is USPS's own code for the record; the cd append is the mapped district, with its number, name and the congress it belongs to. Always read notices. ZIP_CORRECTED means the match is in a different ZIP than the one supplied. SECONDARY_NEEDED means the building has multiple units and an apartment or suite number should be requested. SECONDARY_NOT_VERIFIED means a supplied unit could not be confirmed against known ranges. PARTIAL_MATCH means some details are unverified. A failed match returns success false, sometimes with no notice explaining why, so check success rather than assuming the data block is populated. Without an API key the standardised address is returned with the +4 masked.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The address on one line. A city and state, or a ZIP Code, helps but neither is required — '1600 Pennsylvania Ave NW, Washington DC' and '1600 Pennsylvania Ave NW 20500' both resolve. Between 9 and 300 characters once spacing is normalised. | |
| include | No | Data to append to the match, spelled exactly as the REST API's /v2/address include flags, each costing one extra credit. 'coordinates' adds the latitude and longitude. 'census' adds the county, county subdivision, place, tract, block group and CBSA the address falls in; 'cd' adds its congressional district; 'state_leg' adds its upper and lower state legislative districts; 'school_district' adds its school district; 'timezone' adds the time zone at the matched point. census_YYYY, cd_YYYY and state_leg_YYYY add those boundaries as of a TIGER/Line year (the bare flag is the newest year, answered under `current`; other years under their own key). The 'acs_tract_*' values add an American Community Survey 5-year profile for the address's census tract: four profiles (demographic, social, economic, housing), unsuffixed for the current release or acs_tract_PROFILE_YYYY for an earlier one, in one schema, so a tract can be compared across years. Accepted: coordinates, census, cd, state_leg, school_district, timezone, acs_tract_demographic, acs_tract_social, acs_tract_economic, acs_tract_housing; census_YYYY, cd_YYYY, state_leg_YYYY for YYYY 2010-2025; acs_tract_demographic_YYYY, acs_tract_social_YYYY, acs_tract_economic_YYYY, acs_tract_housing_YYYY for YYYY 2022-2024. A bare flag is its newest year. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly/idempotent), and the description goes well beyond them: tolerance for slips versus ambiguous input, the notice semantics (ZIP_CORRECTED, SECONDARY_NEEDED, etc.), 'check success rather than assume the data block is populated', the credit cost per include flag, and the masked +4 without an API key.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose and scope, then format, then notices. Dense but each block earns its place; it runs long, though the tool's complexity (two params with many include flags and multiple notices) justifies it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so the description carries the return-value burden and does so: it lists the standardized-field return, ZIP/+4, confidence levels and masking, plus all notices and failure-mode behavior. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage the baseline is 3, but the description adds meaning: the ordering rules for the one-line address, the distinction between the USPS cd already in details and the mapped cd appended via include, and the credit cost of each included flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('validate and standardise a US street address') plus the distinctive output (
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions for when and how to use it: 'Send the address on one line in mailing order', 'Send what the user gave you, in proper order, once', and 'If it does not match, report that; do not keep trying rewrites.' It also states the non-use case (Canada) and the cost model for the include flags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Statistics about US ZIP Codes and Canadian postal codes: how many exist, how they break down by type, delivery point and carrier route totals, per-state tables, and ranked lists such as the ZIP Codes with the most carrier routes. Every figure is generated from a stored query against the source data, with the date it was measured. Costs nothing and needs no key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: figures come from a stored query against the source data, are dated with the measurement date, cost nothing and need no key — useful freshness and auth/cost disclosure beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and then a tight enumeration of the available figures, followed by provenance and cost facts. It is a single dense sentence with a long list, but every clause carries information; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only aggregator with no output schema, the description effectively substitutes for the return-value documentation by enumerating the categories of figures returned (counts, breakdowns, tables, ranked lists) and adds freshness and cost context. Nothing an agent needs before calling it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify about inputs, and it correctly spends no words on them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise resource and scope: aggregate statistics about US ZIP Codes and Canadian postal codes, including counts, type/delivery-point/carrier-route breakdowns, per-state tables and ranked lists. This is clearly distinct from lookup-oriented siblings like zip_lookup or quick_zip, though it never names them, so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance and no mention of alternatives such as zip_lookup or quick_zip, which an agent must disambiguate against. The implied use case (wanted aggregate statistics rather than a single code's details) is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | A US ZIP Code, ZIP+4, Canadian FSA, or Canadian postal code. For example 90210, 90210-1234, M5V, or M5V 2T6. | |
| include | No | Enrichments, 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_years | No | Alias, 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). |
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.
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.
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.
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.
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.
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
about_datacity_name_rulescounty_referencedistancemetro_area_referencequick_zipradius_searchsuggest_placesvalidate_addresszip_factszip_lookupUS address intelligence: 120M+ addresses, verify, suggest, reverse geocode, coverage stats.
US ZIP code intelligence: demographics, weather, tax, crime, housing, voting, and more.
AI-operated: US address to districts, legislators, governor and mayor; Google Civic-compatible
Geocode US addresses to census tracts and add ACS demographics. Runs on Apify.
Add one secure layer between your agents and this server.
