Update to Mapbox

{
  "name": "mapbox-geospatial-operations",
  "description": "Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs",
  "included_files": [
    {
      "relative_path": "evals/evals.json",
      "size_in_bytes": 5142
    }
  ],
  "skill_md_contents": "---\nname: mapbox-geospatial-operations\ndescription: Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs\n---\n\n# Mapbox Geospatial Operations Skill\n\nExpert guidance for AI assistants on choosing the right geospatial tools from the Mapbox MCP Server. Focuses on selecting tools based on **what the problem requires** - geometric calculations vs routing, straight-line vs road network, and accuracy needs.\n\n## Core Principle: Problem Type Determines Tool Choice\n\nThe Mapbox MCP Server provides two categories of geospatial tools:\n\n1. **Offline Geometric Tools** - Use Turf.js for pure geometric/spatial calculations\n2. **Routing & Navigation APIs** - Use Mapbox APIs when you need real-world routing, traffic, or travel times\n\n**The key question: What does the problem actually require?**\n\n### Decision Framework\n\n| Problem Characteristic                                 | Tool Category     | Why                                      |\n| ------------------------------------------------------ | ----------------- | ---------------------------------------- |\n| **Straight-line distance** (as the crow flies)         | Offline geometric | Accurate for geometric distance          |\n| **Road/path distance** (as the crow drives)            | Routing API       | Only routing APIs know road networks     |\n| **Travel time**                                        | Routing API       | Requires routing with speed/traffic data |\n| **Point containment** (is X inside Y?)                 | Offline geometric | Pure geometric operation                 |\n| **Geographic shapes** (buffers, centroids, areas)      | Offline geometric | Mathematical/geometric operations        |\n| **Traffic-aware routing**                              | Routing API       | Requires real-time traffic data          |\n| **Route optimization** (best order to visit)           | Routing API       | Complex routing algorithm                |\n| **High-frequency checks** (e.g., real-time geofencing) | Offline geometric | Instant response, no latency             |\n\n## Decision Matrices by Use Case\n\n### Distance Calculations\n\n**User asks: \"How far is X from Y?\"**\n\n| What They Actually Mean                            | Tool Choice                         | Why                                      |\n| -------------------------------------------------- | ----------------------------------- | ---------------------------------------- |\n| Straight-line distance (as the crow flies)         | `distance_tool`                     | Accurate for geometric distance, instant |\n| Driving distance (as the crow drives)              | `directions_tool`                   | Only routing knows actual road distance  |\n| Walking/cycling distance (as the crow walks/bikes) | `directions_tool`                   | Need specific path network               |\n| Travel time                                        | `directions_tool` or `matrix_tool`  | Requires routing with speed data         |\n| Distance with current traffic                      | `directions_tool` (driving-traffic) | Need real-time traffic consideration     |\n\n**Example: \"What's the distance between these 5 warehouses?\"**\n\n- As the crow flies → `distance_tool` (10 calculations, instant)\n- As the crow drives → `matrix_tool` (5×5 matrix, one API call, returns actual route distances)\n\n**Key insight:** Use the tool that matches what \"distance\" means in context. Always clarify: crow flies or crow drives?\n\n### Proximity and Containment\n\n**User asks: \"Which points are near/inside this area?\"**\n\n| Query Type                   | Tool Choice                                           | Why                                                           |\n| ---------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |\n| \"Within X meters radius\"     | `distance_tool` + filter                              | Simple geometric radius                                       |\n| \"Within X minutes drive\"     | `isochrone_tool` → `point_in_polygon_tool`            | Need routing for travel-time zone, then geometric containment |\n| \"Inside this polygon\"        | `point_in_polygon_tool`                               | Pure geometric containment test                               |\n| \"Reachable by car in 30 min\" | `isochrone_tool`                                      | Requires routing + traffic                                    |\n| \"Nearest to this point\"      | `distance_tool` (geometric) or `matrix_tool` (routed) | Depends on definition of \"nearest\"                            |\n\n**Example: \"Are these 200 addresses in our 30-minute delivery zone?\"**\n\n1. Create zone → `isochrone_tool` (routing API - need travel time)\n2. Check addresses → `point_in_polygon_tool` (geometric - 200 instant checks)\n\n**Key insight:** Routing for creating travel-time zones, geometric for containment checks\n\n### Routing and Navigation\n\n**User asks: \"What's the best route?\"**\n\n| Scenario                            | Tool Choice                         | Why                               |\n| ----------------------------------- | ----------------------------------- | --------------------------------- |\n| A to B directions                   | `directions_tool`                   | Turn-by-turn routing              |\n| Optimal order for multiple stops    | `optimization_tool`                 | Solves traveling salesman problem |\n| Clean GPS trace                     | `map_matching_tool`                 | Snaps to road network             |\n| Just need bearing/compass direction | `bearing_tool`                      | Simple geometric calculation      |\n| Route with traffic                  | `directions_tool` (driving-traffic) | Real-time traffic awareness       |\n| Fixed-order waypoints               | `directions_tool` with waypoints    | Routing through specific points   |\n\n**Example: \"Navigate from hotel to airport\"**\n\n- Need turn-by-turn → `directions_tool`\n- Just need to know \"it's northeast\" → `bearing_tool`\n\n**Key insight:** Routing tools for actual navigation, geometric tools for directional info\n\n### Area and Shape Operations\n\n**User asks: \"Create a zone around this location\"**\n\n| Requirement               | Tool Choice      | Why                      |\n| ------------------------- | ---------------- | ------------------------ |\n| Simple circular buffer    | `buffer_tool`    | Geometric circle/radius  |\n| Travel-time zone          | `isochrone_tool` | Based on routing network |\n| Calculate area size       | `area_tool`      | Geometric calculation    |\n| Simplify complex boundary | `simplify_tool`  | Geometric simplification |\n| Find center of shape      | `centroid_tool`  | Geometric centroid       |\n\n**Example: \"Show 5km coverage around each store\"**\n\n- 5km radius → `buffer_tool` (geometric circles)\n- \"What customers can reach in 15 min?\" → `isochrone_tool` (routing-based)\n\n**Key insight:** Geometric tools for distance-based zones, routing tools for time-based zones\n\n## Performance and Scale Considerations\n\n### When Volume Affects Tool Choice\n\n**Small operations (< 100 calculations):**\n\n- Geometric tools: Instant, iterate freely\n- Routing APIs: Fast enough for most uses\n\n**Medium operations (100-1,000 calculations):**\n\n- Geometric tools: Still fast, no concerns\n- Routing APIs: Consider batch operations (matrix_tool)\n\n**Large operations (> 1,000 calculations):**\n\n- Geometric tools: May need optimization but still fast\n- Routing APIs: Definitely use batch tools (matrix_tool handles up to 25×25)\n\n**Key insight:** Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency\n\n### Real-Time vs Batch\n\n| Use Case                            | Approach             | Tool Choice                              |\n| ----------------------------------- | -------------------- | ---------------------------------------- |\n| Real-time geofencing (every second) | Geometric checks     | `point_in_polygon_tool` (instant)        |\n| Route planning (one-time)           | Full routing         | `directions_tool` or `optimization_tool` |\n| Periodic proximity checks           | Geometric distance   | `distance_tool`                          |\n| Live traffic routing                | Routing with traffic | `directions_tool` (driving-traffic)      |\n\n**Architecture note for high-frequency geofencing:** If the application calls containment checks at very high rates (e.g., 50 vehicles every 2 seconds = 25 checks/second), calling MCP tools over the network adds agent-reasoning overhead that makes it impractical. In those cases, recommend using Turf.js directly in-process (`turf.booleanPointInPolygon`) for the hot path, and reserve MCP tools for peripheral tasks like zone definition (`isochrone_tool`), rerouting (`directions_tool`), or visualization (`static_map_image_tool`).\n\n## Common Scenarios and Optimal Approaches\n\n### Scenario 1: Store Locator\n\n**User: \"Find the closest store and show 5km coverage\"**\n\n**Optimal approach:**\n\n1. Search stores → `category_search_tool` (returns distances automatically)\n2. Create coverage zone → `buffer_tool` (5km geometric circle)\n3. Visualize → `static_map_image_tool`\n\n**Why:** Search already gives distances; geometric buffer for simple radius\n\n### Scenario 2: Delivery Route Optimization\n\n**User: \"Optimize delivery to 8 addresses / stops\"**\n\n**Optimal approach:**\n\n1. **Geocode addresses (if needed)** → Use `search_and_geocode_tool` to convert any street addresses to coordinates. Even when coordinates are already provided, mention this as an optional pre-step — real-world delivery lists often contain a mix of addresses and coordinates.\n2. **Optimize route** → `optimization_tool` (TSP solver — reorders stops to minimize total drive time)\n\n**Why `optimization_tool` and NOT these alternatives:**\n\n- **`directions_tool`** only routes A → B (or through fixed-order waypoints). It does NOT reorder stops — if you pass 8 stops, it routes them in the order given, which is almost never optimal.\n- **`matrix_tool`** gives travel times between all pairs of stops (8×8 = 64 values), but it does NOT compute the optimal ordering. You'd need to solve TSP yourself on top of the matrix — `optimization_tool` does this for you in one call.\n\nAlways mention `search_and_geocode_tool` as a useful companion for geocoding delivery addresses before optimization.\n\n### Scenario 3: Service Area Validation\n\n**User: \"Which of these 200 addresses can we deliver to in 30 minutes?\"**\n\n**Optimal approach:**\n\n1. Create delivery zone → `isochrone_tool` (30-minute driving)\n2. Check each address → `point_in_polygon_tool` (200 geometric checks)\n\n**Why:** Routing for accurate travel-time zone, geometric for fast containment checks\n\n### Scenario 4: GPS Trace Analysis\n\n**User: \"How long was this bike ride?\"**\n\n**Optimal approach:**\n\n1. Clean GPS trace → `map_matching_tool` (snap to bike paths)\n2. Get distance → Use API response or calculate with `distance_tool`\n\n**Why:** Need road/path matching; distance calculation either way works\n\n### Scenario 5: Coverage Analysis\n\n**User: \"What's our total service area?\"**\n\n**Optimal approach:**\n\n1. Create buffers around each location → `buffer_tool`\n2. Calculate total area → `area_tool`\n3. Or, if time-based → `isochrone_tool` for each location\n\n**Why:** Geometric for distance-based coverage, routing for time-based\n\n## Anti-Patterns: Using the Wrong Tool Type\n\n### ❌ Don't: Use geometric tools for routing questions\n\n```javascript\n// WRONG: User asks \"how long to drive there?\"\ndistance_tool({ from: A, to: B });\n// Returns 10km as the crow flies, but actual drive is 15km\n\n// CORRECT: Need routing for driving distance\ndirections_tool({\n  coordinates: [\n    { longitude: A[0], latitude: A[1] },\n    { longitude: B[0], latitude: B[1] }\n  ],\n  routing_profile: 'mapbox/driving'\n});\n// Returns actual road distance and drive time as the crow drives\n```\n\n**Why wrong:** As the crow flies ≠ as the crow drives\n\n### ❌ Don't: Use routing APIs for geometric operations\n\n```javascript\n// WRONG: Check if point is in polygon\n// (Can't do this with routing APIs)\n\n// CORRECT: Pure geometric operation\npoint_in_polygon_tool({ point: location, polygon: boundary });\n```\n\n**Why wrong:** Routing APIs don't do geometric containment\n\n### ❌ Don't: Confuse \"near\" with \"reachable\"\n\n```javascript\n// User asks: \"What's reachable in 20 minutes?\"\n\n// WRONG: 20-minute distance at average speed\ndistance_tool + calculate 20min * avg_speed\n\n// CORRECT: Actual routing with road network\nisochrone_tool({\n  coordinates: {longitude: startLng, latitude: startLat},\n  contours_minutes: [20],\n  profile: \"mapbox/driving\"\n})\n```\n\n**Why wrong:** Roads aren't straight lines; traffic varies\n\n### ❌ Don't: Use routing when bearing is sufficient\n\n```javascript\n// User asks: \"Which direction is the airport?\"\n\n// OVERCOMPLICATED: Full routing\ndirections_tool({\n  coordinates: [\n    { longitude: hotel[0], latitude: hotel[1] },\n    { longitude: airport[0], latitude: airport[1] }\n  ]\n});\n\n// BETTER: Just need bearing\nbearing_tool({ from: hotel, to: airport });\n// Returns: \"Northeast (45°)\"\n```\n\n**Why better:** Simpler, instant, answers the actual question\n\n## Hybrid Approaches: Combining Tool Types\n\nSome problems benefit from using both geometric and routing tools:\n\n### Pattern 1: Routing + Geometric Filter\n\n```\n1. directions_tool → Get route geometry\n2. buffer_tool → Create corridor around route\n3. category_search_tool → Find POIs in corridor\n4. point_in_polygon_tool → Filter to those actually along route\n```\n\n**Use case:** \"Find gas stations along my route\"\n\n### Pattern 2: Routing + Distance Calculation\n\n```\n1. category_search_tool → Find 10 nearby locations\n2. distance_tool → Calculate straight-line distances (geometric)\n3. For top 3, use directions_tool → Get actual driving time\n```\n\n**Use case:** Quickly narrow down, then get precise routing for finalists\n\n### Pattern 3: Isochrone + Containment\n\n```\n1. isochrone_tool → Create travel-time zone (routing)\n2. point_in_polygon_tool → Check hundreds of addresses (geometric)\n```\n\n**Use case:** \"Which customers are in our delivery zone?\"\n\n## Decision Algorithm\n\nWhen user asks a geospatial question:\n\n```\n1. Does it require routing, roads, or travel times?\n   YES → Use routing API (directions, matrix, isochrone, optimization)\n   NO → Continue\n\n2. Does it require traffic awareness?\n   YES → Use directions_tool or isochrone_tool with traffic profile\n   NO → Continue\n\n3. Is it a geometric/spatial operation?\n   - Distance between points (straight-line) → distance_tool\n   - Point containment → point_in_polygon_tool\n   - Area calculation → area_tool\n   - Buffer/zone → buffer_tool\n   - Direction/bearing → bearing_tool\n   - Geometric center → centroid_tool\n   - Bounding box → bounding_box_tool\n   - Simplification → simplify_tool\n\n4. Is it a search/discovery operation?\n   YES → Use search tools (search_and_geocode, category_search)\n```\n\n## Key Decision Questions\n\nBefore choosing a tool, ask:\n\n1. **Does \"distance\" mean as the crow flies or as the crow drives?**\n   - As the crow flies (straight-line) → geometric tools\n   - As the crow drives (road distance) → routing APIs\n\n2. **Does the user need travel time?**\n   - Yes → routing APIs (only they know speeds/traffic)\n   - No → geometric tools may suffice\n\n3. **Is this about roads/paths or pure spatial relationships?**\n   - Roads/paths → routing APIs\n   - Spatial relationships → geometric tools\n\n4. **Does this need to happen in real-time with low latency?**\n   - Yes + geometric problem → offline tools (instant)\n   - Yes + routing problem → use routing APIs (still fast)\n\n5. **Is accuracy critical, or is approximation OK?**\n   - Critical + routing → routing APIs\n   - Approximation OK → geometric tools may work\n\n## Terminology Guide\n\nUnderstanding what users mean:\n\n| User Says             | Usually Means                                      | Tool Type   |\n| --------------------- | -------------------------------------------------- | ----------- |\n| \"Distance\"            | Context-dependent! Ask: crow flies or crow drives? | Varies      |\n| \"How far\"             | Often as the crow drives (road distance)           | Routing API |\n| \"Nearby\"              | Usually as the crow flies (straight-line radius)   | Geometric   |\n| \"Close\"               | Could be either - clarify!                         | Ask         |\n| \"Reachable\"           | Travel-time based (crow drives with traffic)       | Routing API |\n| \"Inside/contains\"     | Geometric containment                              | Geometric   |\n| \"Navigate/directions\" | Turn-by-turn routing                               | Routing API |\n| \"Bearing/direction\"   | Compass direction (crow flies)                     | Geometric   |\n\n## Quick Reference\n\n### Geometric Operations (Offline Tools)\n\n- `distance_tool` - Straight-line distance between two points\n- `bearing_tool` - Compass direction from A to B\n- `midpoint_tool` - Midpoint between two points\n- `point_in_polygon_tool` - Is point inside polygon?\n- `area_tool` - Calculate polygon area\n- `buffer_tool` - Create circular buffer/zone\n- `centroid_tool` - Geometric center of polygon\n- `bbox_tool` - Min/max coordinates of geometry\n- `simplify_tool` - Reduce geometry complexity\n\n### Routing & Navigation (APIs)\n\n- `directions_tool` - Turn-by-turn routing\n- `matrix_tool` - Many-to-many travel times\n- `optimization_tool` - Route optimization (TSP)\n- `isochrone_tool` - Travel-time zones\n- `map_matching_tool` - Snap GPS to roads\n\n### When to Use Each Category\n\n**Use Geometric Tools When:**\n\n- Problem is spatial/mathematical (containment, area, bearing)\n- Straight-line distance is appropriate\n- Need instant results for real-time checks\n- Pure geometry (no roads/traffic involved)\n\n**Use Routing APIs When:**\n\n- Need actual driving/walking/cycling distances\n- Need travel times\n- Need to consider road networks\n- Need traffic awareness\n- Need route optimization\n- Need turn-by-turn directions\n\n## REST API honesty (Directions / Isochrone)\n\nWhen generating browser demos against Mapbox REST APIs (not only MCP tools):\n\n### Directions — use the route object metrics\n\n```javascript\nconst route = data.routes[0];\n// GOOD — meters / seconds from the API\nstats.textContent =\n  `Distance ${(route.distance / 1000).toFixed(2)} km · ` + `Duration ${Math.round(route.duration / 60)} min`;\n\n// BAD — cosmetic labels or hardcoded ETAs that look like a working demo\n// \"Len 0.00 km · Time 2 min\" / Math.round(120/60)\n```\n\n### Isochrone — request multiple contours when the prompt asks for bands\n\n```javascript\n// GOOD — three travel-time bands\n`contours_minutes=15,30,60`;\n\n// BAD — a single contour when the UX needs 15 / 30 / 60\n`contours_minutes=30`;\n```\n\n## Integration with Other Skills\n\n**Works with:**\n\n- **mapbox-search-patterns**: Search for locations, then use geospatial operations\n- **mapbox-web-performance-patterns**: Optimize rendering of geometric calculations\n- **mapbox-token-security**: Ensure requests use properly scoped tokens\n\n## Resources\n\n- [Mapbox MCP Server](https://github.com/mapbox/mcp-server)\n- [Turf.js Documentation](https://turfjs.org/) (Powers geometric tools)\n- [Mapbox Directions API](https://docs.mapbox.com/api/navigation/directions/)\n- [Mapbox Isochrone API](https://docs.mapbox.com/api/navigation/isochrone/)\n- [Mapbox Matrix API](https://docs.mapbox.com/api/navigation/matrix/)\n- [Mapbox Optimization API](https://docs.mapbox.com/api/navigation/optimization/)\n"
}