LLMs know about the world but can't see it. Without grounding, a model will confidently invent addresses, distances, and business details — some real, some not. Grounding connects the model's outputs (and inputs) to live, verifiable data at inference time.
Mapbox is one grounding source — but not the only one, and not trying to be. The power comes from combining sources that each contribute a different layer of reality.
| Source | What it grounds |
|---|---|
| Web search (Brave, Bing, etc.) | Current reviews, social proof, cultural reputation, recent news |
| Structured data (Yelp, Foursquare) | Hours, ratings, attributes, photos |
| Mapbox | Spatial reality — coordinates, reachability, real routes, optimal ordering |
| LLM knowledge | Taste, curation, intent understanding, synthesis |
No single source is sufficient. Web search doesn't know if you can walk there in 15 minutes. Mapbox doesn't know if the dive bar has a good jukebox. The LLM knows both, approximately — but its knowledge has a cutoff and it hallucinates specifics.
The LLM generates something and Mapbox validates or enriches it.
Existence & location — LLM says "Zeitgeist on Valencia St" → geocode it → does it exist? Real coordinates?
Attribute enrichment — place_details_tool returns hours, rating, review count, photos, phone, website, price level, popularity score — structured facts the LLM would otherwise hallucinate.
Current reputation — Brave Search returns recent reviews and blog posts. LLM knowledge has a cutoff; web search grounds it in what people are saying now.
Spatial feasibility — LLM plans a trip → isochrone reveals you cannot reach stop 3 in 15 min on foot. LLM estimates "10-minute walk" → Directions API says 28 minutes.
The user doesn't know what they're looking for. Mapbox generates the candidate set; the LLM reasons over it.
Vibe → web search → LLM synthesis "Best dive bars in SF" → Brave returns current lists → LLM synthesizes consensus, filters by what's near the user
Vibe → Mapbox → LLM synthesis "Dog-friendly spot near Dolores Park" → Mapbox returns POIs within a 10-min isochrone with the right attributes → LLM narrates options
Combined
- Web search: cultural layer ("locals love this place")
- Mapbox: spatial layer ("8 minutes away, open until midnight")
- LLM: synthesizes into a recommendation that feels like talking to someone who knows both the city and you
The human never has to know the business name, category tag, or search query. Intent goes in; a grounded answer comes out.
| Tool | What it grounds |
|---|---|
ground_location_tool |
One-shot: given coordinates, returns the place name, nearby POIs by category, and reachability contours — all fetched in parallel. The Swiss Army knife of spatial grounding. |
search_and_geocode_tool |
Find and locate places by name or query |
category_search_tool |
Find places by type near a location (restaurants, cafes, parks…) |
place_details_tool |
Rich details for a known place: hours, rating, reviews, photos, phone, website, price level, popularity |
reverse_geocode_tool |
What address or neighborhood is at these coordinates? |
| Tool | What it grounds |
|---|---|
directions_tool |
Real route, distance, and travel time between A and B |
isochrone_tool |
What area is actually reachable within X minutes by walking/driving/cycling? |
matrix_tool |
Real travel times between every pair in a set of locations |
optimization_tool |
Optimal order to visit N stops on a real road network |
map_matching_tool |
Snap a GPS trace to actual roads — grounds noisy location data |
These ground a category LLMs are particularly bad at: combinatorial decisions on real road networks.
An LLM asked to order 8 stops optimally is guessing from approximate geography — there are 40,320 possible orderings and it has no real travel time data. The Matrix API provides actual pairwise travel times, turning a guessing problem into a computation. The Optimization API returns the genuinely shortest route given real roads and constraints.
This matters for delivery routing, field service scheduling, multi-stop trip planning — any "visit N places efficiently" problem. It also grounds trade-off questions: "Should I go to the Embarcadero or SoMa first?" becomes answerable with real numbers.
These ground spatial reasoning — things the LLM literally cannot compute correctly without real geometry:
| Tool | What it grounds |
|---|---|
points_within_polygon_tool |
Which locations fall inside this area? (delivery zones, service regions, neighborhoods) |
buffer_tool |
The real area within X meters of a point or route |
intersect_tool |
Do these two areas actually overlap? |
distance_tool |
Real distance between two coordinates |
area_tool |
Real area of a polygon |
nearest_point_tool |
Which of these locations is genuinely closest? |
bounding_box_tool |
Bounding extent of a set of features |
A question like "is this address in our delivery zone?" is a spatial containment problem — not a language problem. The LLM cannot answer it correctly without real geometry operations.
| Tool | What it grounds |
|---|---|
static_map_image_tool |
Renders a real map image with markers, paths, and overlays |
Visual grounding is underrated: showing someone a map of what was just discussed is often more convincing than any amount of text. It also surfaces errors instantly — a misplaced marker is immediately obvious on a map in a way that a wrong address in prose is not.
Everything above gets more powerful once you have the user's real coordinates.
- "Near me" is meaningless without a real position
- Reachability replaces straight-line distance with real travel time on actual road networks
- Time of day matters: traffic, hours of operation, last entry times
The combination answers "what's the best option for me, right now, given where I am and what I care about" — something no single source can do alone.
MCP server — exposes all of the above as callable tools so Claude (or any LLM) can reach live spatial data mid-conversation, composing freely with other tools like Brave Search or Yelp.
Skills — pre-packaged expertise on when to call which tool, in what order, and how to combine results from multiple sources. The difference between Claude knowing the tools exist and knowing how to orchestrate them effectively for a given task.