{"id":15402,"plugin_id":"plugin_asdk_app_6a2c0bf33cb48191884d842b15ad3c20","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:11:22.375Z","digest":"13a9d771b53cc73e2da0a319d6930fd13ebceb1f8c2acf08cba3ec9b82b92604","against":null,"payload":{"name":"mapbox-location-grounding","description":"Compose Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of training data","included_files":[{"relative_path":"evals/evals.json","size_in_bytes":7185}],"skill_md_contents":"---\nname: mapbox-location-grounding\ndescription: Compose Mapbox MCP tools to produce grounded, cited location-aware responses from live data instead of training data\n---\n\n# Mapbox Location Grounding Skill\n\nTeaches 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.\n\n## When to Use Grounding\n\nGround responses when the user asks about:\n\n- \"What's near [location]?\" or \"What's around [coordinate]?\"\n- \"Describe this neighborhood / area\"\n- \"Find [category] within walking/driving distance\"\n- \"What can I do near [address]?\"\n- \"How long does it take to get from A to B?\"\n- \"What's within a 10-minute walk of here?\"\n- \"How far is it between these locations?\"\n- Real estate, travel, mobility, or local discovery use cases\n- Any question where place accuracy, recency, or travel time matters\n\n**Never answer location questions from training data alone.** Always retrieve live data.\n\n## Grounding Tool Composition\n\n### Preferred: single tool call\n\nIf `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:\n\n```\nground_location_tool(\n  longitude, latitude,\n  query: \"restaurant\",   // optional — category or subcategory of nearby places to find\n  profile: \"mapbox/walking\",    // optional — travel profile for isochrone\n  contours_minutes: [5, 10, 15]\n)\n```\n\nReturns:\n\n- Neighborhood/place name from reverse geocoding\n- Nearby POIs with distances, ratings, price levels, and popularity (when available)\n- Travel-time reachability from isochrone\n- A static map image for visual context\n- Citations for all data sources\n\nDo not call `reverse_geocode_tool`, `category_search_tool`, `place_details_tool`, or `isochrone_tool` separately — they are already composed inside this tool.\n\n### Query parameter\n\nThe `query` parameter accepts **category or subcategory terms** — not attribute preferences:\n\n- Supported: `\"restaurant\"`, `\"coffee\"`, `\"park\"`, `\"Italian restaurant\"`, `\"EV charging station\"`\n- Not supported: `\"family-friendly\"`, `\"fast charging\"`, `\"outdoor seating\"` — these are not filterable attributes in Mapbox data\n\nTo 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.\n\n### Fallback: manual composition\n\nIf `ground_location_tool` is not available, build the grounded response by composing these tools in order:\n\n#### Step 1 — Establish place context\n\n```\nreverse_geocode_tool(longitude, latitude, types: \"neighborhood,locality,place\")\n```\n\nReturns: neighborhood, city, region, country. This is the anchor for the response.\n\n#### Step 2 — Retrieve nearby POIs\n\nFor specific names or brands:\n\n```\nsearch_and_geocode_tool(query, proximity: {longitude, latitude}, limit: 10)\n```\n\nFor generic categories:\n\n```\ncategory_search_tool(category, proximity: {longitude, latitude}, limit: 10)\n```\n\n#### Step 3 — Enrich POIs with ratings and price (optional but high-value)\n\nFor each POI with a `mapbox_id`, call in parallel:\n\n```\nplace_details_tool(mapbox_id, attribute_sets: [\"visit\"])\n```\n\nReturns: rating, price level, popularity, and opening hours per place.\n\n#### Step 4 — Add travel-time context (optional but high-value)\n\n```\nisochrone_tool(\n  coordinates: {longitude, latitude},\n  profile: \"mapbox/walking\",    // or \"mapbox/driving\", \"mapbox/cycling\", \"mapbox/driving-traffic\"\n  contours_minutes: [5, 10, 15]\n)\n```\n\nReturns a polygon showing what's reachable within each time threshold.\n\n#### Step 5 — Visual grounding (optional)\n\n```\nstatic_map_image_tool(longitude, latitude, zoom: 14)\n```\n\nReturns a map image that can be included in the response for visual context.\n\n## Grounded Response Structure\n\nAlways structure grounded responses with explicit citations:\n\n```\nPlace: [neighborhood, city from reverse_geocode]\nNearby [category]: [list from search/category tool, with names, ratings, prices, and distances]\nTravel context: [X min walk / Y min drive from isochrone]\nSources: Mapbox Search, Mapbox Directions (live data)\n```\n\nExample grounded response:\n\n> **SoMa, San Francisco, CA** (live Mapbox data)\n>\n> Restaurants within walking distance:\n>\n> - Bix Restaurant $$ ★8.4 — 56 Gold St (180m)\n> - The Bird $ ★7.9 — 115 New Montgomery St (320m)\n> - Oren's Hummus $$ ★8.1 — 131 Townsend St (510m)\n>\n> Reachable by walking: 5 min, 10 min, 15 min\n>\n> _Sources: Mapbox Geocoding API, Mapbox Search API, Mapbox Place Details API, Mapbox Isochrone API, Mapbox Static Images API_\n\n## Routing Grounding\n\nFor 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`.\n\n### Point-to-point travel time and distance\n\n> \"How long does it take to drive from Pike Place Market to Capitol Hill?\"\n> \"What's the fastest route from the hotel to the airport?\"\n\n```\ndirections_tool(\n  waypoints: [{longitude, latitude}, {longitude, latitude}],\n  profile: \"mapbox/driving-traffic\"   // live traffic; or \"mapbox/walking\", \"mapbox/cycling\", \"mapbox/driving\"\n)\n```\n\nReturns: 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.\n\n### Area reachability (\"within X minutes\")\n\n> \"What's reachable within a 10-minute walk?\"\n> \"Show me what I can reach in 15 minutes by car from here\"\n\n```\nisochrone_tool(\n  coordinates: {longitude, latitude},\n  profile: \"mapbox/walking\",\n  contours_minutes: [5, 10, 15]\n)\n```\n\nReturns 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.\n\n### Multi-location travel time matrix\n\n> \"Which of these three offices is closest to my location?\"\n> \"What are travel times from this warehouse to each of our delivery zones?\"\n> \"Compare commute times to multiple locations\"\n\nUse `matrix_tool` — **do NOT call `directions_tool` separately for each pair**. Matrix batches all pairs in a single API call.\n\n```\nmatrix_tool(\n  sources: [{longitude, latitude}, ...],\n  destinations: [{longitude, latitude}, ...],\n  profile: \"mapbox/driving-traffic\"\n)\n```\n\nReturns 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.\n\n### Proximity search with routing context\n\nFor \"find [category] within X minutes of [location]\":\n\n1. Geocode the origin if needed: `search_and_geocode_tool(address)`\n2. Get the reachable area: `isochrone_tool(coordinates, profile, contours_minutes)`\n3. Search for POIs: `ground_location_tool(longitude, latitude, query: \"category\")` — the isochrone\n   contours tell the user what's within each time band\n\nOr more directly: `ground_location_tool` returns both nearby POIs and isochrone reachability in one\ncall, which covers most proximity + routing use cases without additional composition.\n\n### Example routing response\n\n> **Pike Place Market → Capitol Hill, Seattle**\n>\n> By car (with traffic): 12 min, 3.2 km via Pine St\n> By walking: 28 min, 2.1 km\n> By cycling: 14 min, 2.3 km\n>\n> _Source: Mapbox Directions API (live traffic)_\n\n## What Mapbox Grounding Offers vs. Training Data\n\n|                    | Training Data       | Mapbox Grounding            |\n| ------------------ | ------------------- | --------------------------- |\n| POI accuracy       | Stale, hallucinated | Live, verified              |\n| Ratings/price      | Often wrong         | Live via Place Details      |\n| Business hours     | Often wrong         | Live via Place Details      |\n| Travel times       | Estimated           | Live traffic via Directions |\n| Reachable area     | Not available       | Isochrone polygons          |\n| Multi-stop routing | Not available       | Up to 25 waypoints          |\n| New places         | Missing             | Indexed                     |\n| Map image          | None                | Inline static map           |\n| Citations          | None                | Tool + API source           |\n\n## Important Limitations\n\n- **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.\n- **POI coverage** varies by region. If search returns few results, say so rather than padding with guesses.\n- **Coordinates required** for proximity search — if the user provides an address, geocode it first with `search_and_geocode_tool` before running category search.\n\n## Anti-Patterns to Avoid\n\n- Answering \"what's near X?\" from training data without calling search tools\n- Estimating travel times without calling `directions_tool` or `isochrone_tool`\n- Hallucinating business names, hours, or ratings\n- Calling `reverse_geocode_tool` + `category_search_tool` + `place_details_tool` separately when `ground_location_tool` is available\n- Using attribute terms like \"family-friendly\" as the query parameter — use the category instead\n- Returning raw tool output without synthesizing into a readable response\n- Omitting citations — always indicate the response is grounded in live Mapbox data\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}