GeoWire is a geo-intelligence gateway providing a unified MCP server for location-based operations across multiple map/place data providers.
Search Places (search_places): Find businesses, POIs, and landmarks by query, optionally filtered by location, radius, country, category, or open-now status.
Get Place Details (get_place): Retrieve full details for a specific place using a provider reference ID (e.g., google:ChIJ...).
Geocode Address (geocode_address): Convert a street address or place name into geographic coordinates and a normalized address.
Reverse Geocode (reverse_geocode): Convert coordinates into the nearest street address or place name.
Get Directions (get_directions): Get driving, walking, or cycling routes between two or more waypoints, including distance, travel time, and per-leg breakdown — no API key required (OSRM/OpenStreetMap).
Distance Matrix (distance_matrix): Compute an N×M matrix of travel distances and times between multiple origins and destinations — no API key needed.
Analyze Area (analyze_area): Perform commercial/market analysis for a given center + radius, returning category density, competition overview, rating landscape, and top places.
Get Demographics (get_demographics): Retrieve US Census demographic data (population, median age, median household income) for a coordinate's area — free Census API key required.
Get Isochrone (get_isochrone): Compute a travel-time reachability polygon (e.g., "15-minute drive catchment") as GeoJSON — no API key required.
List Providers (list_geo_providers): Discover configured geo data providers, their capabilities, enabled state, priority, and attribution requirements.
Key highlights: Works zero-config with no API keys (OpenStreetMap + OSRM as defaults), supports multi-provider merging/deduplication, provider fallback, cost budgets, and routing strategies. Supports 10 providers including Nominatim, OSRM, Google, Yelp, Foursquare, Census, Kakao, Naver, Baidu, and custom CSV data.
Provides access to Foursquare's place data, including ratings, reviews, and category information, for enhanced commercial-area analysis and place search.
Integrates Google Maps data for place search, geocoding, and detailed place information, requiring an API key. Contributes ratings, reviews, hours, and more.
Provides free, no-key-required place search, geocoding, and routing via OpenStreetMap data, including Nominatim and OSRM services.
Adds Yelp's business data, including ratings, reviews, and hours, for enriched place search and market analysis in US/Western regions.
Give any AI agent real-world location intelligence in 5 minutes — no API key required.
One interface for place search, directions, and area/market analysis across every map provider.
GeoWire is an open-source geo intelligence gateway that sits between AI agents and map/place data providers (OpenStreetMap, Google, Yelp, Foursquare, US Census, your own data) and exposes them through a single MCP server, REST API, and SDK. One interface for place search, geocoding, directions & distance matrices, and commercial-area analysis (density, ratings, demographics) — with provider fallback, multi-provider merge + dedup, cost budgets, and a policy engine that enforces each provider's caching/attribution terms.
Published on npm — MCP · REST · CLI · SDK all functional. 10 providers, 8 operations.
Honest by design: OpenStreetMap (the zero-key default) is a great geocoder — strong on place names, addresses, and landmarks — but thin on category words ("coffee", "pharmacy"), ratings, and hours. For US/Western commercial data, add a Google, Yelp, or Foursquare key (BYOK) — GeoWire merges them and tells you which source every field came from. Directions run key-free on OpenStreetMap routing (OSRM); US demographics come from the Census (free key).
Contents: Why · Quickstart · MCP tools · REST · Anatomy of a response · Config · Providers · Recipes & examples · Roadmap · Architecture
Direct integration | Single-provider MCP | GeoWire | |
Unified place schema | ❌ per-provider code | ❌ | ✅ |
Provider fallback on failure | ❌ | ❌ | ✅ |
Multi-provider merge + dedup | ❌ | ❌ | ✅ |
Cost budgets & routing | ❌ | ❌ | ✅ |
Works without any API key | ❌ | depends | ✅ (OSM by default) |
Self-hosted | — | depends | ✅ |
Your own place data as a provider | ❌ | ❌ | ✅ |
Transparent provenance (which source, what cost) | ❌ | ❌ | ✅ (every response) |
Not a Google replacement — it uses Google. The thing no single provider can do: merge your own store data + Google + OSM into one deduped record, with per-field provenance (your name is authoritative, Google adds ratings, OSM adds coordinates). Real run below:
Once your agent can find places, it can reason about areas. One analyze_area
call turns a point + radius into a commercial-district read — category density,
competition, the rating landscape, and (in the US) demographics:
// "Is this a good block for a new café?" — SF, 1 km radius
{ "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radiusMeters": 1000,
"categories": ["cafe", "restaurant", "bar"] }
// → per-category counts + density/km², avg rating (Google/Yelp), price mix,
// an activity proxy (Yelp review volume), and Census demographics for the tract.Same gateway also does directions & distance matrices and travel-time isochrones — key-free via OSRM — so an agent can rank candidates by drive time and answer catchment questions like "what's within a 15-minute drive of this address?" See Recipes.
Related MCP server: chuk-mcp-geocoder
Add this to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):
{
"mcpServers": {
"geowire": { "command": "npx", "args": ["-y", "@geowirehq/mcp"] }
}
}Then ask: "Where is the Golden Gate Bridge?", "Find coffee within 2 km of
37.7749, -122.4194 (San Francisco).", or "How do I drive from downtown SF to
Fisherman's Wharf?" Works with zero API keys — OpenStreetMap + OSRM routing
are the defaults. Add "env": { "GOOGLE_MAPS_API_KEY": "..." } (or YELP_API_KEY)
for ratings, reviews, and hours, and "CENSUS_API_KEY" for area demographics.
See more MCP client configs.
npx @geowirehq/cli search "Golden Gate Bridge" # terminal search with a results table
npx @geowirehq/cli search "coffee" --near 37.7749,-122.4194 --radius 2000 # near a coordinate
npx @geowirehq/cli reverse 37.8199,-122.4783 # coordinate → nearest place
npx @geowirehq/cli route 37.7749,-122.4194 37.8083,-122.4156 # driving directions (no key, OSRM)
npx @geowirehq/cli get google:ChIJ... # one place by reference (getPlace-capable provider)
npx @geowirehq/cli # start the REST + MCP server (zero-config)
npx @geowirehq/cli init # interactive setup wizard (.env + config)
npx @geowirehq/cli test # check provider connectionsAdd --json to any command for the full response (results + provenance meta).
docker run -p 4980:4980 geowire/geowire
# then:
curl -X POST http://localhost:4980/v1/places/search \
-H 'content-type: application/json' \
-d '{"query":"coffee","near":{"latitude":37.7749,"longitude":-122.4194},"radiusMeters":2000}'Or with docker compose up (see docker-compose.yml). API docs at /docs.
import { createGeoWire } from "@geowirehq/core";
import { createNominatimProvider } from "@geowirehq/provider-nominatim";
const geo = createGeoWire({ providers: [createNominatimProvider()] });
const { results, meta } = await geo.searchPlaces({
query: "coffee",
near: { latitude: 37.7749, longitude: -122.4194 },
radiusMeters: 2000,
});Full embedded-SDK guide: examples/typescript-sdk.md.
Tool | Description |
| Natural-language + coordinate/region place search |
| Details by |
| Address → coordinates (+ normalized address) |
| Coordinates → nearest address |
| Route between waypoints (distance, time, legs) — no key (OSRM) |
| N×M travel distances/times — rank candidates by drive time — no key |
| Commercial-area analysis: category density, competition, rating landscape, demographics |
| Travel-time reachability polygon ("what's within a 15-min drive") — no key (OSRM) |
| Population / age / income for a coordinate's area (US Census, free key) |
| Active providers, capabilities, status (agent self-awareness) |
Every response includes both a human-readable summary and structuredContent
(schema-valid JSON).
Method | Path | |
POST |
| search |
GET |
| place details ( |
GET |
| geocode |
GET |
| reverse geocode |
POST |
| directions between waypoints (no key) |
POST |
| N×M travel distance/time matrix (no key) |
POST |
| commercial-area analysis (density, competition, ratings, demographics) |
POST |
| travel-time reachability polygon (no key) |
GET |
| area demographics (US Census, free key) |
GET |
| list providers |
GET |
| health check |
GET |
| Prometheus metrics |
GET |
| Swagger UI (OpenAPI 3.1) |
POST |
| MCP over Streamable HTTP |
Optional Bearer auth: set GEOWIRE_API_KEYS=key1,key2.
No black box. Every response carries a meta block: which providers were
used / skipped / failed (and why), dedup counts, cache status, estimated
cost, and per-field sourcing — so you always know where each value came from.
{
"results": [{
"id": "gwp_CvWvRZrFtegkJPxP9CW0",
"name": "Golden Gate Bridge",
"location": { "latitude": 37.8199286, "longitude": -122.4782551 },
"sources": [{
"provider": "nominatim",
"providerPlaceId": "way/27385590",
"fields": ["name", "location", "categories", "address"] // ← what this source contributed
}],
"attributions": ["© OpenStreetMap contributors"]
}],
"meta": {
"providersUsed": [{ "provider": "nominatim", "resultCount": 1, "latencyMs": 2449 }],
"providersSkipped": [], // e.g. { provider: "google", reason: "MISSING_CREDENTIALS" | "QUOTA_EXCEEDED" }
"providersFailed": [], // e.g. { provider: "google", reason: "TIMEOUT" }
"strategy": "first-success",
"cache": { "hit": false }
// merging adds: "dedup": { "before": 3, "after": 1 }
// paid provider: "estimatedCostUSD": 0.032
}
}After a merge, sources[].fields shows (say) the phone came from Google while
the coordinates came from OSM. Walkthrough: docs/recipes.md.
geowire.config.yaml:
providers:
nominatim: { enabled: true } # default ON, no key (search/geocode)
osrm: { enabled: true } # default ON, no key (directions)
google: { enabled: true, apiKey: ${GOOGLE_MAPS_API_KEY} }
yelp: { enabled: true } # env YELP_API_KEY (US/Western business & reviews)
census: { enabled: true } # env CENSUS_API_KEY (US demographics, free)
kakao: { enabled: true } # env KAKAO_REST_API_KEY (KR)
internal: { enabled: true, source: ./my-places.csv, priority: 100 }
routing:
defaultStrategy: merge # first-success | merge | cost-aware | weighted | fastest
providerWeights: # for `weighted`: order by priority·cost·coverage
priority: 0.5
cost: 0.3
coverage: 0.2
budget:
perRequestMaxUSD: 0.10 # over-budget paid providers are skipped, free ones usedKeys come from the environment (${VAR}), never committed in plaintext.
Provider | Key? | Capabilities |
| none | search, geocode, reverseGeocode |
| none | route, distanceMatrix |
| BYOK | search, geocode, reverseGeocode, getPlace, route, distanceMatrix |
| BYOK | search, geocode, reverseGeocode |
| BYOK | search, geocode |
| BYOK | search, geocode, reverseGeocode |
| BYOK | search, getPlace |
| BYOK | search, getPlace |
| BYOK | demographics |
| none | search |
Regional providers make Korea (Kakao/Naver) and China (Baidu) coverage first-class where OSM is thin and Google has gaps — Baidu returns BD-09 coordinates, which GeoWire converts to WGS84 automatically. Merge them all + your own store data into one deduped record.
Providers aren't interchangeable; they're complementary. When merge combines
duplicates, GeoWire doesn't just pick the highest-priority provider's whole record —
it sources each field from the provider that's authoritative for it. Every
provider declares its strengths in its manifest (fieldAuthority), so one merged
place can carry OSM's coordinates, Google's reviews, and Kakao's local name at once:
Provider | Authoritative for | Role |
Nominatim / OSM |
| base map geometry & addresses |
| rich business data | |
Foursquare |
| global POI specialist |
Kakao / Naver / Baidu |
| country-specific local names |
Internal (your CSV) |
| your own data is the source of truth |
sources[].fields in every response records which provider contributed which field.
This is the "Stripe for Maps" idea in code: you get one clean place record, and each
part of it comes from whoever knows it best. (Reviews/photos are provider originals —
the policy engine enforces each provider's storage terms; Google originals aren't cached.)
Want another provider? See CONTRIBUTING.md — "Write a provider in 30 minutes".
docs/recipes.md — end-to-end recipes: near+radius search, merge + dedup, cost budgets, country routing, your own CSV, self-host.
examples/mcp-clients.md — configs for Claude Desktop/Code, Cursor, Cline, VS Code, Windsurf.
examples/typescript-sdk.md — embed the SDK.
examples/llm-tool-use.md — raw OpenAI / Anthropic function calling. Also LangChain · Vercel AI SDK.
v0.1 is deliberately "It works" scope. Honest about what's not in it yet:
Area | Shipped | Planned |
Operations | search, geocode, reverse-geocode, get-place, directions, distance-matrix, area analysis, isochrones | autocomplete (typed, not wired) |
Strategies |
| — (all 5 shipped) |
Field sourcing | role-based merge (each provider's authoritative fields) | per-field config overrides |
Routing providers | OSRM (no key), Google Routes (BYOK) | Mapbox, Valhalla, HERE |
Routing | explicit | country inference from coordinates |
Analysis | category density / competition / rating landscape, US demographics, activity proxy, isochrones (travel-time catchment) | real foot-traffic (paid data), exact isochrones (ORS/Valhalla), Korea demographics (SGIS) |
Cache | in-memory (LRU) | Redis adapter |
Providers | OSM, OSRM, Google, Yelp, Foursquare, Census, Kakao, Naver, Baidu, your CSV | Mapbox, HERE, TomTom, … (community PRs welcome) |
Rate limiting | per-provider (OSM 1 req/s) | global / per-endpoint |
AI agent / app
│ MCP · REST · SDK
▼
GeoWire core ── pipeline: plan → execute → normalize → dedup → rank → policy → cache
│ GeoProvider contract
▼
providers: nominatim · osrm · google · yelp · foursquare · census · kakao · naver · baidu · internal · (community)Monorepo packages: schema · provider-sdk · provider-testkit · core ·
providers/* · mcp · apps/server · cli.
Recipes / cookbook — task-oriented, copy-pasteable
Examples — MCP clients, SDK, LangChain, AI SDK, tool use
Apache-2.0. GeoWire's code license is separate from the terms of third-party map/place data providers — usage of Google, Mapbox, HERE, Kakao, Naver, etc. is governed by each provider's own terms. OSM data is under ODbL; GeoWire's policy engine enforces attribution and caching limits per provider.
Analyze a commercial area / neighborhood: given a center point, radius, and business types, return how many of each exist nearby, their density (per km²), rating landscape, and top places. Use this for market/competition questions — 'how saturated is coffee here', 'is this a good spot for a bakery', 'what's the dining scene within 1km'. Example: {"center": {"latitude": 37.4979, "longitude": 127.0276}, "radiusMeters": 1000, "categories": ["cafe", "restaurant", "convenience store"]}. Works with any configured providers; richer with Google/Foursquare (ratings). Not demographic data — it's a place-density/competition view built from live search.
| Name | Required | Description | Default |
|---|---|---|---|
| center | Yes | ||
| options | No | ||
| categories | Yes | ||
| radiusMeters | Yes | ||
| limitPerCategory | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses return values (counts, density, ratings, top places), data source dependencies (richer with some providers), and what it is not (demographic). It does not mention any destructive or permission requirements, which is acceptable for a read-only analysis tool.
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?
The description is well-structured: starts with purpose, then usage examples, provider info, and a caveat. It is reasonably concise but could be slightly tighter; the example is helpful.
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?
Given 5 parameters (with nested objects) and no output schema, the description covers the core parameters and high-level output structure. However, it does not specify the exact output format or describe the optional 'options' parameters fully, leaving some gaps.
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 0%, so description must compensate. It explains the key parameters (center, radius, categories) through text and an example. However, the 'options' object (with language, strategy, etc.) is not described, leaving its purpose unclear.
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 clearly states the tool analyzes a commercial area using center, radius, and business types, and returns density, ratings, and top places. It explicitly distinguishes from demographic tools and sibling tools like search_places by describing its aggregated 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?
The description provides explicit use cases (e.g., 'how saturated is coffee here') and an example. It mentions it works with providers and is not demographic data. However, it does not directly compare to siblings like search_places or state when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute a matrix of travel distances and times from each origin to each destination (N origins × M destinations) in one call. No API key needed. Use this to rank/compare many candidates by drive time — e.g. 'which of these 5 stores is closest to the customer' or delivery/logistics assignment. Example: {"origins": [{"latitude": 37.57, "longitude": 126.98}], "destinations": [{"latitude": 37.49, "longitude": 127.02}, {"latitude": 37.51, "longitude": 127.05}]}. rows[i][j] is origins[i] → destinations[j]. Public OSRM supports driving only.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | driving | |
| options | No | ||
| origins | Yes | ||
| destinations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It explains output structure (rows[i][j]) and mentions no API key needed. However, it omits rate limits, maximum array sizes, idempotency, and side effects. The driving-only note is helpful but incomplete regarding provider fallback.
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?
The description is concise (5 sentences) and front-loaded with the core action. The example and output structure explanation are well-placed. Minor improvement: the OSRM note at the end could be integrated earlier for context.
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?
Given no output schema, the description explains the return array mapping, which is vital. However, it lacks units (e.g., km, seconds), error handling, and constraints on input size or provider behavior. Siblings like get_directions are not explicitly compared. Overall, sufficient for basic use but incomplete for complex scenarios.
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 0%, so the description must compensate. Only origins and destinations are explained with an example; the mode and options parameters (with complex nested properties) are not described at all. Users lack guidance on how to set mode or configure options like providers or timeout.
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 clearly states it computes a matrix of travel distances and times from N origins to M destinations in one call. It distinguishes itself from siblings like get_directions by emphasizing the matrix aspect and use cases like comparing multiple candidates.
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 concrete use cases (ranking stores, delivery logistics) and mentions 'No API key needed' and 'Public OSRM supports driving only.' However, it does not explicitly state when not to use it (e.g., for a single route, use get_directions) and the mode restriction contradicts the schema's enum (walking, cycling) without clarifying when those modes are valid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a street address or place name into geographic coordinates and a normalized address. Use this when you have an address string and need latitude/longitude. Example: {"address": "1600 Amphitheatre Parkway, Mountain View, CA"}. To search for businesses by name/category, use search_places.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| address | Yes | ||
| country | No | ||
| options | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It states the output (coordinates + normalized address) but omits behavioral details like multiple results, error handling, or normalization specifics. Adequate but not rich.
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?
Two sentences with a concrete example, no filler. All information is front-loaded and earns its place.
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?
Moderate complexity (4 params, nested options, no output schema) but description is very brief. Missing guidance on limit control, country parameter, and the rich options object. Does not mention return format or behavior for multiple 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 description coverage is 0%. Description only provides an example for 'address' and does not explain 'limit', 'country', or the 'options' object with its nested properties (language, strategy, providers, etc.). The description adds minimal semantics beyond the schema.
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?
Description clearly states 'Convert a street address or place name into geographic coordinates and a normalized address.' It uses a specific verb and resource, and distinguishes from sibling search_places by explicitly naming the alternative.
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 guidance: 'Use this when you have an address string and need latitude/longitude.' and 'To search for businesses by name/category, use search_places.' This tells the agent when to use and when not to, with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get demographics (population, median age, median household income, households) for the area containing a coordinate. Use this for market context — 'who lives around here', income/age of an area. Requires a demographics provider: US Census (free key, US only). Returns null outside coverage. Example: {"location": {"latitude": 37.7749, "longitude": -122.4194}}. For a full commercial picture combine with analyze_area, which folds this in automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| location | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses provider dependency, coverage limitation (returns null outside), and gives an example. While it doesn't explicitly state read-only, it's implied. Minor gap: no mention of side effects or cost implications from maxCostUSD.
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?
Description is front-loaded with purpose, includes example, and avoids redundancy. Could be slightly tighter by merging market context and provider requirement, but overall efficient.
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?
Given complexity (nested params, no output schema), description covers main data returned, usage context, and coverage. But missing details on options parameter and how to configure providers. Adequate for basic understanding but not fully complete.
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 0%, but description only explains location with an example, not options parameters (language, strategy, providers, timeoutMs, maxCostUSD). The provider requirement is mentioned but not linked to the providers field. Inadequate for a 2-parameter tool with nested objects.
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?
Description clearly states verb 'Get demographics' and specific data points (population, median age, median household income, households). It distinguishes from sibling tools by referencing analyze_area as an automatic alternative.
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 specifies when to use ('market context'), provides provider requirements (US Census, free key, US only), mentions null outside coverage, and suggests combining with analyze_area. Clear guidance on when not to use standalone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a route (driving directions) between two or more waypoints, with total distance, travel time, and per-leg breakdown. Works with no API key (OpenStreetMap routing via OSRM). Use this for 'how do I get from A to B', 'how far by car', or 'how long to drive' questions. Waypoints are {latitude, longitude} in order (start, [via...], end). Example: {"waypoints": [{"latitude": 37.5665, "longitude": 126.9780}, {"latitude": 37.4979, "longitude": 127.0276}]}. Set geometry:true to also get the route polyline. Note: the public OSRM server supports driving only.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | driving | |
| options | No | ||
| geometry | No | ||
| waypoints | Yes | ||
| alternatives | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states that the public OSRM server supports driving only, but the input schema allows walking and cycling, creating a contradiction. No info on permissions, rate limits, or error handling.
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?
The description is concise and well-structured: purpose, use cases, waypoint format, example, geometry toggle, and a caveat. Every sentence adds value.
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?
Given the complexity (5 params, nested objects, no output schema), the description covers the core functionality but omits details on mode, options, and alternatives. The contradiction about modes further reduces completeness.
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 0%, so the description must compensate. It explains waypoints with an example and mentions the geometry parameter. However, it fails to explain mode (despite the contradiction), options, or alternatives parameters.
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 clearly states it gets a route with driving directions, total distance, travel time, and per-leg breakdown. It specifies the source (OSRM, no API key) and distinguishes from siblings like geocoding or place search tools.
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 explicitly says when to use this tool: 'how do I get from A to B', etc. It also notes no API key required. However, it does not mention when not to use or point to alternatives like distance_matrix for distance-only queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute a travel-time reachability area (isochrone): from an origin, the region reachable within N minutes of driving/walking/cycling, as a GeoJSON polygon + area in km². No API key (OpenStreetMap routing). Use for site selection / catchment questions — 'what's within a 15-minute drive', 'how big is this store's 10-min catchment'. Example: {"origin": {"latitude": 37.7749, "longitude": -122.4194}, "minutes": 15, "mode": "driving"}. It's an approximation (sampled bearings scored by a distance matrix), not a routing-engine isochrone.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | driving | |
| origin | Yes | ||
| minutes | Yes | ||
| options | No | ||
| bearings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that it uses OpenStreetMap without an API key and that it is an approximation via sampled bearings. It also mentions the output format (GeoJSON polygon + area). It does not cover rate limits, authentication, or error behavior, but the core behavioral traits are 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?
The description is a single, well-structured paragraph. The first sentence defines the tool, followed by usage context, a concrete example, and a note on limitations. Every sentence adds value, with no redundancy or 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?
Given the tool has 5 parameters, no output schema, and no annotations, the description covers the main purpose, example usage, and key limitations. It lacks details on the output structure and error scenarios, but the complexity is partially addressed. The completeness is good but not exhaustive.
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 schema has 0% parameter descriptions, so the description must compensate. It provides an example covering origin, minutes, and mode, and mentions bearings briefly. However, it does not explain the 'options' sub-parameters (language, strategy, providers, timeoutMs, maxCostUSD), leaving gaps. The coverage is partial, earning a baseline 3.
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 clearly states the tool computes a travel-time reachability area (isochrone) as a GeoJSON polygon with area. The verb 'compute' and the resource 'isochrone' are precise. The purpose is distinct from sibling tools like get_directions or distance_matrix, which focus on point-to-point routes rather than area coverage.
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 explicitly recommends the tool for site selection and catchment questions, with concrete examples. It notes the approximation nature, implying not to use for precise routing. However, it does not name specific alternative tools or list cases where the tool should not be used, which would have earned a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full details for a single place by its provider reference id, in the form 'provider:providerPlaceId' (e.g. 'google:ChIJN1t_tDeuEmsRUsoyG83frY4'), as found in a place's sources. Only providers that support getPlace can resolve a reference — currently Google (needs an API key). OpenStreetMap/Nominatim does not, so a 'nominatim:...' reference returns nothing; use search_places or geocode_address for OSM instead. Internal 'gwp_' ids cannot be resolved directly. Example: {"id": "google:ChIJN1t_tDeuEmsRUsoyG83frY4"}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| options | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses which providers support getPlace (only Google) and that OSM/Nominatim does not, and that internal ids cannot be resolved. This is good transparency about limitations, though it lacks details on rate limits, performance, or side effects.
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?
The description is a single paragraph that front-loads the purpose. It is reasonably concise and avoids unnecessary words, but could be more structured (e.g., bullet points for limitations). Each sentence adds value, and no information is redundant.
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?
Given the tool's complexity (nested options, no output schema), the description covers the core functionality and limitations well but omits all details about the 'options' parameter and return values. This makes it incomplete for an agent to fully understand how to configure the call or 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 description coverage is 0%, so description must compensate. It explains the 'id' parameter format and gives an example, but completely ignores the 'options' object (with 5 nested parameters like language, strategy, providers, timeoutMs, maxCostUSD). This is a significant gap, leaving the agent uninformed about half the parameters.
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 clearly states the tool's purpose: 'Fetch full details for a single place by its provider reference id'. It specifies the input format (e.g., 'google:...') and distinguishes itself from siblings by noting that for OSM references, one should use 'search_places' or 'geocode_address' instead.
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 states when to use (resolving provider references) and when not (OSM references and internal 'gwp_' ids). Provides alternatives (search_places, geocode_address for OSM) and mentions the prerequisite of an API key for Google. This gives clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the geo data providers currently configured, with their capabilities, enabled state, priority, and required attribution. Use this to understand which data sources are available (e.g. whether Google is configured) before choosing a strategy or explaining coverage. Takes no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it lists configured providers with specific attributes, and notes it takes no arguments. Adequate for a read-only tool, though no mention of caching or side effects.
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?
Two efficient sentences: first states functionality with details, second provides usage guidance. No extraneous 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?
Given no parameters and no output schema, the description sufficiently describes what the tool returns (capabilities, enabled state, priority, attribution) and when to use it (before strategy selection). Perfectly adequate for a list discovery tool.
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?
No parameters defined, so baseline is 4 as per rules. The description confirms it takes no arguments, adding clarity over the empty schema.
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 uses specific verb 'List' and resource 'geo data providers', detailing the returned fields (capabilities, enabled state, priority, attribution). It clearly distinguishes from siblings like search_places or geocode by focusing on provider discovery, not querying.
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 usage context: 'Use this to understand which data sources are available... before choosing a strategy or explaining coverage.' This guides the agent when to call this tool, though it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert geographic coordinates into the nearest address / place. Example: {"location": {"latitude": 37.5665, "longitude": 126.9780}}.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| location | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions conversion but does not disclose behavioral details such as provider selection, cost implications, language support, timeout, or error handling. The example only shows input, not behavior.
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?
The description is very short (two sentences) but sacrifices clarity. It is under-specified for a tool with nested parameters. Conciseness is achieved at the cost of completeness.
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?
Given the complexity of the input schema (nested options object with multiple properties) and no output schema, the description is incomplete. It does not explain the return value format, optional parameters, or behavior under different strategies. The example is helpful but insufficient.
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 0%, so the description must compensate. It only illustrates the 'location' parameter via example and completely ignores the 'options' parameter with its five sub-properties (language, strategy, providers, timeoutMs, maxCostUSD). No meaning is added beyond the schema.
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 clearly states the action 'convert' and the resource 'geographic coordinates into nearest address/place'. An example is provided. It implicitly distinguishes from the sibling tool 'geocode_address' (which does the reverse). However, it does not explicitly use the term 'reverse geocode' or mention the output type.
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 usage when you have coordinates and need an address, but provides no explicit guidance on when to use this tool versus alternatives like 'search_places' or 'geocode_address'. There are no exclusions or context for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for places (businesses, points of interest, landmarks) by a natural-language query, optionally biased to a coordinate (near) and/or restricted to a country. Returns places ranked by relevance/distance, each with location, address, contact, opening hours, and its data source(s). Use this for 'find X near Y' requests. Example: {"query": "24-hour pharmacy", "near": {"latitude": 10.7769, "longitude": 106.7009}, "radiusMeters": 2000}. To turn an address into coordinates use geocode_address instead; to look up one known place use get_place.
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | ||
| limit | No | ||
| query | Yes | ||
| country | No | ||
| openNow | No | ||
| options | No | ||
| categories | No | ||
| radiusMeters | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry burden. It discloses ranking by relevance/distance and result contents (location, address, contact, hours, sources). Could be more explicit about side effects, but adequate.
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?
Single paragraph with example and sibling distinction, efficient but example adds length. Overall well-structured and front-loaded with purpose.
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?
Given 8 parameters, nested objects, and no output schema, description covers main use case and result contents. Missing error handling and defaults for some params, but sufficient for typical use.
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 0%, so description must compensate. It explains 'query', 'near', 'radiusMeters', 'country' via example and text, but leaves 'limit', 'openNow', 'options', 'categories' vague. Partial coverage.
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 clearly states the tool's purpose: 'Search for places... by a natural-language query', distinguishing it from siblings like geocode_address and get_place.
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 explicit guidance: 'Use this for 'find X near Y' requests' and directs to alternatives (geocode_address for address-to-coordinates, get_place for known places).
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.
v0.1.0analyze_areadistance_matrixgeocode_addressget_demographicsget_directionsget_isochroneget_placelist_geo_providersreverse_geocodesearch_placesScored across 10 tools
Each tool has a clear, distinct purpose. For example, search_places handles natural-language queries, get_place retrieves by specific ID, and geocode_address converts addresses to coordinates, with descriptions explicitly clarifying boundaries.
All tool names follow a consistent verb_noun pattern with lowercase and underscores, making the set predictable and easy to navigate.
10 tools cover the core geo service functionalities without unnecessary extras, striking a good balance between completeness and simplicity.
The tool set provides comprehensive coverage for common geo tasks: searching, geocoding, routing, distance matrices, area analysis, demographics, and isochrones, with no obvious gaps.
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
OpenCage forward + reverse geocoding (free key, 2500/day)
Geocoding, weather forecasts, and timezone lookups
