Local SEO Data

Official

Overview Schema Source Related Servers Discussions(1)Admin

location_search

Read-only

Resolve city and place names to exact location formats for local SEO tools, returning codes, types, and parent data; disambiguate duplicate municipalities with a state filter.

Instructions

Use when resolving city names to the exact format needed by other tools. Call this when a tool returns no results for a location or when the format is ambiguous. Returns name, code, type (location taxonomy: City, County, State, DMA Region, ...), state, country, and parent_code, plus total_count and a truncated flag. IMPORTANT for multi-location ambiguity: many municipalities exist twice (e.g. "Hamilton" AND "Hamilton Township" in NJ — different entities with very different search volumes); pass a bare place name plus the state param to see all of them. Free (0 credits).

Input Schema

Name	Required	Description
`q`	Yes	Place name (e.g. "Cherry Hill" or "Austin, TX"). Prefer a bare name + state param over baking the state into q.
`limit`	No	Max results. Default: 10
`state`	No	State/province filter, name or abbreviation (e.g. "NJ"). Scopes matching without hiding suffixed entities like townships.
`country`	No	Country filter (e.g. "United States" or "US")

Output Schema

Name	Required	Description	Default
`locations`	Yes
`truncated`	No
`total_count`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.1.0Oct 22, 2026

addedInput schema / properties / country

Added value: +{
+  "description": "Country filter (e.g. \"United States\" or \"US\")",
+  "type": "string"
+}

changedInput schema / properties / q / description

Previous value: -"Location query (e.g. \"Orchard Park\" or \"Austin TX\")"New value: +"Place name (e.g. \"Cherry Hill\" or \"Austin, TX\"). Prefer a bare name + state param over baking the state into q."

addedInput schema / properties / state

Added value: +{
+  "description": "State/province filter, name or abbreviation (e.g. \"NJ\"). Scopes matching without hiding suffixed entities like townships.",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "locations": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "code": {
+            "type": "number"
+          },
+          "country": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "parent_code": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "state": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "code",
+          "type",
+          "country",
+          "state"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total_count": {
+      "type": "number"
+    },
+    "truncated": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "locations"
+  ],
+  "type": "object"
+}

First observedv0.1.0May 11, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: free at 0 credits, truncated flag on results, and the substantive warning that many municipalities exist twice (Hamilton vs. Hamilton Township) with different search volumes. It loses a point because the return-field enumeration duplicates the output schema rather than adding to it.

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 usage trigger and tightly written, with the ambiguity warning given the emphasis it deserves. The one wasted clause is the list of returned fields, which the output schema already supplies.

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?

For a four-parameter read-only resolver with a full output schema, the description covers every decision an agent must make: when to invoke, how to disambiguate, what shape the answer comes in, and that it costs nothing. Nothing material 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 baseline would be 3. The description goes beyond it by explaining why the state param is preferable to baking the state into q — it scopes matching without hiding suffixed entities like townships. That is genuine semantic guidance the schema only asserts, not justifies.

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 and resource — resolving place names to the canonical format other tools require — and names the returned taxonomy (City, County, State, DMA Region). No sibling tool in the list performs this normalization, and the agent can distinguish it immediately from search/listing tools.

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 trigger conditions are given: call it when another tool returns no results for a location or when the location format is ambiguous. It also prescribes the exact invocation pattern for the ambiguous case (bare place name plus the state param) so all suffixed entities are surfaced. This is when-to-use plus how-to-call, not just context.

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