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

Place search (type-ahead)

suggest_places

Read-onlyIdempotent

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.

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

Input Schema

Name	Required	Description
`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.
`api_key`	No	Your ZIP-Codes.com API key, only when you cannot send it as the X-Api-Key or Authorization: Bearer header (for example a key bought with buy_credits in this conversation). Leave it out to use the free tier. It is never shown back in a response.
`country`	No	Restrict to one country. Omit to search both.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 1, 2026

addedInput schema / properties / api_key

Added value: +{
+  "default": null,
+  "description": "Your ZIP-Codes.com API key, only when you cannot send it as the X-Api-Key or Authorization: Bearer header (for example a key bought with buy_credits in this conversation). Leave it out to use the free tier. It is never shown back in a response.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed3 schema fields changedOct 20, 2026
- addedInput schema / properties / near / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- addedInput schema / properties / q / type
```
Added value: +"string"
```
- addedInput schema / properties / state / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedOct 20, 2026

TDQS

A4.6/5.0

Behavior4/5

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

With readOnlyHint/idempotentHint already declared, the description adds real value beyond annotations: fuzzy-match behavior with worked examples, that results are ranked and return a total match count, and an explicit scope warning that "coverage is broad rather than deep — it returns names and codes, not the full record." It stops short of describing empty-result or error behavior, keeping it at 4.

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, then examples, then routing guidance, then caveats — a sound structure. It is slightly dense and repeats the types/near distinction that the schema already carries, which keeps it off a 5.

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?

No output schema exists, yet the description covers the return shape (ranked names and codes plus total matches) and the deliberate depth limit. With 7 parameters and full schema coverage, an agent has everything needed to call it correctly and to know what it gets back.

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; the description adds meaning on top by illustrating what q accepts ("beverley hills", "san fransisco", "902" as a partial code) and characterizing near as a result bias and types as a restriction. No new syntax is introduced, but the intent of q is materially clarified.

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?

The description states a specific verb+resource ("Search for a place by partial name, misspelled name, or partial code") and frames the tool as the resolver feeding other tools. It names the exact kinds of place covered and distinguishes itself from siblings like zip_lookup, radius_search and distance as the upstream lookup step.

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?

Explicit routing: "Reach for this FIRST when the place is vague, misspelled or partial, then pass the resolved code to zip_lookup, radius_search or distance." It also explains the two narrowing options (types, near) and the alternative strategies they represent, leaving nothing to inference.

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 tools Inspect

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.