evals/evals.json
{
"skill_name": "mapbox-location-grounding",
"evals": [
{
"id": 1,
"prompt": "What restaurants are near -87.6298, 41.8781?",
"expected_output": "Should call ground_location_tool with the coordinates and query 'restaurant'. Should NOT call category_search_tool or reverse_geocode_tool separately. Response should include neighborhood name, a list of nearby restaurants with ratings and price levels sourced from live Mapbox data, and cite the Mapbox APIs used.",
"files": [],
"expectations": [
"Calls ground_location_tool — NOT category_search_tool or reverse_geocode_tool",
"Passes query: 'restaurant' (or 'restaurants') to ground_location_tool",
"Response includes a neighborhood or place name (e.g. 'The Loop, Chicago')",
"Response includes nearby restaurant names with distances",
"Response includes ratings or price levels (not fabricated — sourced from tool output)",
"Response cites Mapbox as the data source"
]
},
{
"id": 2,
"prompt": "I'm at 37.7749° N, 122.4194° W in San Francisco. What coffee shops are nearby and which ones have good ratings?",
"expected_output": "Should call ground_location_tool with the coordinates and query 'coffee'. Should return coffee shops enriched with rating and price data from the tool. Should NOT fabricate ratings or recommend specific places from training data without grounding.",
"files": [],
"expectations": [
"Calls ground_location_tool with coordinates and query 'coffee' (or 'coffee shop')",
"Does NOT answer from training data (does not name specific coffee shops without calling the tool)",
"Returns ratings and/or price levels from the tool output — not from training data",
"Response notes that ratings are sourced from live Mapbox data, not fabricated"
]
},
{
"id": 3,
"prompt": "Find me family-friendly Italian restaurants near 40.7128° N, 74.0060° W in New York City.",
"expected_output": "Should call ground_location_tool with query 'Italian restaurant'. Should NOT claim to filter by 'family-friendly' as a data attribute — that isn't available. Should use rating and price level from the enriched POI results to inform a recommendation about which places seem suitable. Should be transparent that family-friendliness is inferred from available data, not a direct filter.",
"files": [],
"expectations": [
"Calls ground_location_tool with query 'Italian restaurant' (not 'family-friendly Italian restaurant')",
"Does NOT claim the search filtered results by 'family-friendly' as a data attribute",
"Uses rating and/or price level from results to make a recommendation",
"Is transparent that family-friendliness is inferred, not directly filterable"
]
},
{
"id": 4,
"prompt": "How long does it take to walk from Pike Place Market to Capitol Hill in Seattle?",
"expected_output": "Should geocode both locations with search_and_geocode_tool (or use known coordinates), then call directions_tool with walking profile. Should return actual walking duration and distance from the routing API — not estimate from training data. Should cite Mapbox Directions API.",
"files": [],
"expectations": [
"Does NOT estimate the walking time from training data",
"Calls directions_tool with profile 'mapbox/walking' (or 'walking')",
"Returns actual duration and distance from the routing API",
"Cites Mapbox Directions API as the source",
"If addresses are provided as text, geocodes them first before calling directions_tool"
]
},
{
"id": 5,
"prompt": "What's reachable within a 15-minute drive from 47.6062° N, 122.3321° W in Seattle?",
"expected_output": "Should call ground_location_tool with profile 'driving' and contours_minutes [15], or call isochrone_tool directly. Should describe the reachable area based on the isochrone result — not estimate from training data. Should NOT confuse this with a directions query.",
"files": [],
"expectations": [
"Calls ground_location_tool with profile 'driving' and contours_minutes including 15, OR calls isochrone_tool directly",
"Does NOT estimate the reachable area from training data",
"Describes the reachable area based on isochrone output (e.g. neighborhoods, area coverage)",
"Does NOT call directions_tool — this is a reachability question, not point-to-point routing"
]
},
{
"id": 6,
"prompt": "I'm building a feature that compares drive times from a user's location to three nearby store locations. I have coordinates for all four points. Should I call directions_tool three times, or is there a better approach with Mapbox MCP tools?",
"expected_output": "Should recommend matrix_tool as the correct approach — one call returns all three drive times simultaneously. Should explain that calling directions_tool three times is inefficient and unnecessary. Should mention that matrix_tool accepts multiple sources and destinations and returns a full duration/distance matrix.",
"files": [],
"expectations": [
"Recommends matrix_tool (not three separate directions_tool calls)",
"Explains that matrix_tool returns all travel times in a single API call",
"Explains why calling directions_tool separately for each pair is inefficient",
"Mentions that matrix_tool results can be used to rank locations by travel time"
]
},
{
"id": 7,
"prompt": "Describe the neighborhood around 51.5074° N, 0.1278° W in London.",
"expected_output": "Should call ground_location_tool with the coordinates and no query (no specific POI category needed). Should return neighborhood name, place context, and reachability from the tool — not describe the neighborhood from training data knowledge.",
"files": [],
"expectations": [
"Calls ground_location_tool with the coordinates",
"Response is grounded in tool output — includes the neighborhood name returned by reverse geocoding",
"Does NOT rely solely on training data knowledge about the location",
"Cites Mapbox as the data source"
]
},
{
"id": 8,
"prompt": "What's the best route from my hotel at 48.8566° N, 2.3522° E in Paris to the Eiffel Tower, and how long will it take to walk?",
"expected_output": "Should geocode 'Eiffel Tower' or use known coordinates, then call directions_tool with walking profile from the hotel coordinates. Should return actual walking duration and turn-by-turn steps. Should NOT estimate walking time from training data.",
"files": [],
"expectations": [
"Does NOT estimate walking time from training data",
"Calls directions_tool with walking profile",
"Returns actual duration from the routing API",
"Optionally geocodes 'Eiffel Tower' with search_and_geocode_tool if coordinates are not known",
"Cites Mapbox Directions API as the source"
]
}
]
}
SKILL.md
---
name: mapbox-location-grounding
description: Compose Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of training data
---
# Mapbox Location Grounding Skill
Teaches AI assistants how to ground location-aware responses in live Mapbox data by composing MCP tools into a structured, cited answer. Use this instead of relying on training data for place names, POIs, ratings, or travel times — which are stale and prone to hallucination.
## When to Use Grounding
Ground responses when the user asks about:
- "What's near [location]?" or "What's around [coordinate]?"
- "Describe this neighborhood / area"
- "Find [category] within walking/driving distance"
- "What can I do near [address]?"
- "How long does it take to get from A to B?"
- "What's within a 10-minute walk of here?"
- "How far is it between these locations?"
- Real estate, travel, mobility, or local discovery use cases
- Any question where place accuracy, recency, or travel time matters
**Never answer location questions from training data alone.** Always retrieve live data.
## Grounding Tool Composition
### Preferred: single tool call
If `ground_location_tool` is available, use it — it handles reverse geocoding, POI search, place details enrichment, isochrone, and a static map image in one call:
```
ground_location_tool(
longitude, latitude,
query: "restaurant", // optional — category or subcategory of nearby places to find
profile: "mapbox/walking", // optional — travel profile for isochrone
contours_minutes: [5, 10, 15]
)
```
Returns:
- Neighborhood/place name from reverse geocoding
- Nearby POIs with distances, ratings, price levels, and popularity (when available)
- Travel-time reachability from isochrone
- A static map image for visual context
- Citations for all data sources
Do not call `reverse_geocode_tool`, `category_search_tool`, `place_details_tool`, or `isochrone_tool` separately — they are already composed inside this tool.
### Query parameter
The `query` parameter accepts **category or subcategory terms** — not attribute preferences:
- Supported: `"restaurant"`, `"coffee"`, `"park"`, `"Italian restaurant"`, `"EV charging station"`
- Not supported: `"family-friendly"`, `"fast charging"`, `"outdoor seating"` — these are not filterable attributes in Mapbox data
To help users find places matching a preference (e.g. "family-friendly"), search by category (`"restaurant"`) and use the returned rating and price data to inform the recommendation.
### Fallback: manual composition
If `ground_location_tool` is not available, build the grounded response by composing these tools in order:
#### Step 1 — Establish place context
```
reverse_geocode_tool(longitude, latitude, types: "neighborhood,locality,place")
```
Returns: neighborhood, city, region, country. This is the anchor for the response.
#### Step 2 — Retrieve nearby POIs
For specific names or brands:
```
search_and_geocode_tool(query, proximity: {longitude, latitude}, limit: 10)
```
For generic categories:
```
category_search_tool(category, proximity: {longitude, latitude}, limit: 10)
```
#### Step 3 — Enrich POIs with ratings and price (optional but high-value)
For each POI with a `mapbox_id`, call in parallel:
```
place_details_tool(mapbox_id, attribute_sets: ["visit"])
```
Returns: rating, price level, popularity, and opening hours per place.
#### Step 4 — Add travel-time context (optional but high-value)
```
isochrone_tool(
coordinates: {longitude, latitude},
profile: "mapbox/walking", // or "mapbox/driving", "mapbox/cycling", "mapbox/driving-traffic"
contours_minutes: [5, 10, 15]
)
```
Returns a polygon showing what's reachable within each time threshold.
#### Step 5 — Visual grounding (optional)
```
static_map_image_tool(longitude, latitude, zoom: 14)
```
Returns a map image that can be included in the response for visual context.
## Grounded Response Structure
Always structure grounded responses with explicit citations:
```
Place: [neighborhood, city from reverse_geocode]
Nearby [category]: [list from search/category tool, with names, ratings, prices, and distances]
Travel context: [X min walk / Y min drive from isochrone]
Sources: Mapbox Search, Mapbox Directions (live data)
```
Example grounded response:
> **SoMa, San Francisco, CA** (live Mapbox data)
>
> Restaurants within walking distance:
>
> - Bix Restaurant $$ ★8.4 — 56 Gold St (180m)
> - The Bird $ ★7.9 — 115 New Montgomery St (320m)
> - Oren's Hummus $$ ★8.1 — 131 Townsend St (510m)
>
> Reachable by walking: 5 min, 10 min, 15 min
>
> _Sources: Mapbox Geocoding API, Mapbox Search API, Mapbox Place Details API, Mapbox Isochrone API, Mapbox Static Images API_
## Routing Grounding
For questions about travel between two locations, use `directions_tool`. For questions about reachable area, use `isochrone_tool`. For comparing travel times across multiple locations, use `matrix_tool`.
### Point-to-point travel time and distance
> "How long does it take to drive from Pike Place Market to Capitol Hill?"
> "What's the fastest route from the hotel to the airport?"
```
directions_tool(
waypoints: [{longitude, latitude}, {longitude, latitude}],
profile: "mapbox/driving-traffic" // live traffic; or "mapbox/walking", "mapbox/cycling", "mapbox/driving"
)
```
Returns: duration (with live traffic), distance, turn-by-turn steps, and an encoded polyline for map rendering. Supports up to 25 waypoints for multi-stop routes.
### Area reachability ("within X minutes")
> "What's reachable within a 10-minute walk?"
> "Show me what I can reach in 15 minutes by car from here"
```
isochrone_tool(
coordinates: {longitude, latitude},
profile: "mapbox/walking",
contours_minutes: [5, 10, 15]
)
```
Returns a polygon showing the area reachable within each time threshold. Combine with `category_search_tool` or `ground_location_tool` to answer "what restaurants are within a 10-minute walk?" — use the isochrone to define the boundary, then search within it.
### Multi-location travel time matrix
> "Which of these three offices is closest to my location?"
> "What are travel times from this warehouse to each of our delivery zones?"
> "Compare commute times to multiple locations"
Use `matrix_tool` — **do NOT call `directions_tool` separately for each pair**. Matrix batches all pairs in a single API call.
```
matrix_tool(
sources: [{longitude, latitude}, ...],
destinations: [{longitude, latitude}, ...],
profile: "mapbox/driving-traffic"
)
```
Returns a matrix of durations and distances between every source/destination pair. Rank results by duration to find the nearest location. One `matrix_tool` call replaces N separate `directions_tool` calls.
### Proximity search with routing context
For "find [category] within X minutes of [location]":
1. Geocode the origin if needed: `search_and_geocode_tool(address)`
2. Get the reachable area: `isochrone_tool(coordinates, profile, contours_minutes)`
3. Search for POIs: `ground_location_tool(longitude, latitude, query: "category")` — the isochrone
contours tell the user what's within each time band
Or more directly: `ground_location_tool` returns both nearby POIs and isochrone reachability in one
call, which covers most proximity + routing use cases without additional composition.
### Example routing response
> **Pike Place Market → Capitol Hill, Seattle**
>
> By car (with traffic): 12 min, 3.2 km via Pine St
> By walking: 28 min, 2.1 km
> By cycling: 14 min, 2.3 km
>
> _Source: Mapbox Directions API (live traffic)_
## What Mapbox Grounding Offers vs. Training Data
| | Training Data | Mapbox Grounding |
| ------------------ | ------------------- | --------------------------- |
| POI accuracy | Stale, hallucinated | Live, verified |
| Ratings/price | Often wrong | Live via Place Details |
| Business hours | Often wrong | Live via Place Details |
| Travel times | Estimated | Live traffic via Directions |
| Reachable area | Not available | Isochrone polygons |
| Multi-stop routing | Not available | Up to 25 waypoints |
| New places | Missing | Indexed |
| Map image | None | Inline static map |
| Citations | None | Tool + API source |
## Important Limitations
- **Attribute filtering** (family-friendly, outdoor seating, fast charging) is not supported by the category search API. Use category terms and let rating/price data inform preference-based recommendations.
- **POI coverage** varies by region. If search returns few results, say so rather than padding with guesses.
- **Coordinates required** for proximity search — if the user provides an address, geocode it first with `search_and_geocode_tool` before running category search.
## Anti-Patterns to Avoid
- Answering "what's near X?" from training data without calling search tools
- Estimating travel times without calling `directions_tool` or `isochrone_tool`
- Hallucinating business names, hours, or ratings
- Calling `reverse_geocode_tool` + `category_search_tool` + `place_details_tool` separately when `ground_location_tool` is available
- Using attribute terms like "family-friendly" as the query parameter — use the category instead
- Returning raw tool output without synthesizing into a readable response
- Omitting citations — always indicate the response is grounded in live Mapbox data