OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add mapbox/mapbox-agent-skills --skill mapbox-geospatial-operations
Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs
npx skills add mapbox/mapbox-agent-skills --skill mapbox-geospatial-operations
Expert 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.
The Mapbox MCP Server provides two categories of geospatial tools:
The key question: What does the problem actually require?
| Problem Characteristic | Tool Category | Why |
|---|---|---|
| Straight-line distance (as the crow flies) | Offline geometric | Accurate for geometric distance |
| Road/path distance (as the crow drives) | Routing API | Only routing APIs know road networks |
| Travel time | Routing API | Requires routing with speed/traffic data |
| Point containment (is X inside Y?) | Offline geometric | Pure geometric operation |
| Geographic shapes (buffers, centroids, areas) | Offline geometric | Mathematical/geometric operations |
| Traffic-aware routing | Routing API | Requires real-time traffic data |
| Route optimization (best order to visit) | Routing API | Complex routing algorithm |
| High-frequency checks (e.g., real-time geofencing) | Offline geometric | Instant response, no latency |
User asks: "How far is X from Y?"
| What They Actually Mean | Tool Choice | Why |
|---|---|---|
| Straight-line distance (as the crow flies) | distance_tool | Accurate for geometric distance, instant |
| Driving distance (as the crow drives) | directions_tool | Only routing knows actual road distance |
| Walking/cycling distance (as the crow walks/bikes) | directions_tool | Need specific path network |
| Travel time | directions_tool or matrix_tool | Requires routing with speed data |
| Distance with current traffic | directions_tool (driving-traffic) | Need real-time traffic consideration |
Example: "What's the distance between these 5 warehouses?"
distance_tool (10 calculations, instant)matrix_tool (5×5 matrix, one API call, returns actual route distances)Key insight: Use the tool that matches what "distance" means in context. Always clarify: crow flies or crow drives?
User asks: "Which points are near/inside this area?"
| Query Type | Tool Choice | Why |
|---|---|---|
| "Within X meters radius" | distance_tool + filter | Simple geometric radius |
| "Within X minutes drive" | isochrone_tool → point_in_polygon_tool | Need routing for travel-time zone, then geometric containment |
| "Inside this polygon" | point_in_polygon_tool | Pure geometric containment test |
| "Reachable by car in 30 min" | isochrone_tool | Requires routing + traffic |
| "Nearest to this point" | distance_tool (geometric) or matrix_tool (routed) | Depends on definition of "nearest" |
Example: "Are these 200 addresses in our 30-minute delivery zone?"
isochrone_tool (routing API - need travel time)point_in_polygon_tool (geometric - 200 instant checks)Key insight: Routing for creating travel-time zones, geometric for containment checks
User asks: "What's the best route?"
| Scenario | Tool Choice | Why |
|---|---|---|
| A to B directions | directions_tool | Turn-by-turn routing |
| Optimal order for multiple stops | optimization_tool | Solves traveling salesman problem |
| Clean GPS trace | map_matching_tool | Snaps to road network |
| Just need bearing/compass direction | bearing_tool | Simple geometric calculation |
| Route with traffic | directions_tool (driving-traffic) | Real-time traffic awareness |
| Fixed-order waypoints | directions_tool with waypoints | Routing through specific points |
Example: "Navigate from hotel to airport"
directions_toolbearing_toolKey insight: Routing tools for actual navigation, geometric tools for directional info
User asks: "Create a zone around this location"
| Requirement | Tool Choice | Why |
|---|---|---|
| Simple circular buffer | buffer_tool | Geometric circle/radius |
| Travel-time zone | isochrone_tool | Based on routing network |
| Calculate area size | area_tool | Geometric calculation |
| Simplify complex boundary | simplify_tool | Geometric simplification |
| Find center of shape | centroid_tool | Geometric centroid |
Example: "Show 5km coverage around each store"
buffer_tool (geometric circles)isochrone_tool (routing-based)Key insight: Geometric tools for distance-based zones, routing tools for time-based zones
Small operations (< 100 calculations):
Medium operations (100-1,000 calculations):
Large operations (> 1,000 calculations):
Key insight: Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency
| Use Case | Approach | Tool Choice |
|---|---|---|
| Real-time geofencing (every second) | Geometric checks | point_in_polygon_tool (instant) |
| Route planning (one-time) | Full routing | directions_tool or optimization_tool |
| Periodic proximity checks | Geometric distance | distance_tool |
| Live traffic routing | Routing with traffic | directions_tool (driving-traffic) |
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).
User: "Find the closest store and show 5km coverage"
Optimal approach:
category_search_tool (returns distances automatically)buffer_tool (5km geometric circle)static_map_image_toolWhy: Search already gives distances; geometric buffer for simple radius
User: "Optimize delivery to 8 addresses / stops"
Optimal approach:
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.optimization_tool (TSP solver — reorders stops to minimize total drive time)Why optimization_tool and NOT these alternatives:
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.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.Always mention search_and_geocode_tool as a useful companion for geocoding delivery addresses before optimization.
User: "Which of these 200 addresses can we deliver to in 30 minutes?"
Optimal approach:
isochrone_tool (30-minute driving)point_in_polygon_tool (200 geometric checks)Why: Routing for accurate travel-time zone, geometric for fast containment checks
User: "How long was this bike ride?"
Optimal approach:
map_matching_tool (snap to bike paths)distance_toolWhy: Need road/path matching; distance calculation either way works
User: "What's our total service area?"
Optimal approach:
buffer_toolarea_toolisochrone_tool for each locationWhy: Geometric for distance-based coverage, routing for time-based
Why wrong: As the crow flies ≠ as the crow drives
Why wrong: Routing APIs don't do geometric containment
Why wrong: Roads aren't straight lines; traffic varies
Why better: Simpler, instant, answers the actual question
Some problems benefit from using both geometric and routing tools:
Use case: "Find gas stations along my route"
Use case: Quickly narrow down, then get precise routing for finalists
Use case: "Which customers are in our delivery zone?"
When user asks a geospatial question:
Before choosing a tool, ask:
Does "distance" mean as the crow flies or as the crow drives?
Does the user need travel time?
Is this about roads/paths or pure spatial relationships?
Does this need to happen in real-time with low latency?
Is accuracy critical, or is approximation OK?
Understanding what users mean:
| User Says | Usually Means | Tool Type |
|---|---|---|
| "Distance" | Context-dependent! Ask: crow flies or crow drives? | Varies |
| "How far" | Often as the crow drives (road distance) | Routing API |
| "Nearby" | Usually as the crow flies (straight-line radius) | Geometric |
| "Close" | Could be either - clarify! | Ask |
| "Reachable" | Travel-time based (crow drives with traffic) | Routing API |
| "Inside/contains" | Geometric containment | Geometric |
| "Navigate/directions" | Turn-by-turn routing | Routing API |
| "Bearing/direction" | Compass direction (crow flies) | Geometric |
distance_tool - Straight-line distance between two pointsbearing_tool - Compass direction from A to Bmidpoint_tool - Midpoint between two pointspoint_in_polygon_tool - Is point inside polygon?area_tool - Calculate polygon areabuffer_tool - Create circular buffer/zonecentroid_tool - Geometric center of polygonbbox_tool - Min/max coordinates of geometrysimplify_tool - Reduce geometry complexitydirections_tool - Turn-by-turn routingmatrix_tool - Many-to-many travel timesoptimization_tool - Route optimization (TSP)isochrone_tool - Travel-time zonesmap_matching_tool - Snap GPS to roadsUse Geometric Tools When:
Use Routing APIs When:
When generating browser demos against Mapbox REST APIs (not only MCP tools):
Works with:
// WRONG: Check if point is in polygon
// (Can't do this with routing APIs)
// CORRECT: Pure geometric operation
point_in_polygon_tool({ point: location, polygon: boundary });// User asks: "What's reachable in 20 minutes?"
// WRONG: 20-minute distance at average speed
distance_tool + calculate 20min * avg_speed
// CORRECT: Actual routing with road network
isochrone_tool({
coordinates: {longitude: startLng, latitude: startLat},
contours_minutes: [20],
profile: "mapbox/driving"
})// User asks: "Which direction is the airport?"
// OVERCOMPLICATED: Full routing
directions_tool({
coordinates: [
{ longitude: hotel[0], latitude: hotel[1] },
{ longitude: airport[0], latitude: airport[1] }
]
});
// BETTER: Just need bearing
bearing_tool({ from: hotel, to: airport });
// Returns: "Northeast (45°)"1. directions_tool → Get route geometry
2. buffer_tool → Create corridor around route
3. category_search_tool → Find POIs in corridor
4. point_in_polygon_tool → Filter to those actually along route1. category_search_tool → Find 10 nearby locations
2. distance_tool → Calculate straight-line distances (geometric)
3. For top 3, use directions_tool → Get actual driving time1. isochrone_tool → Create travel-time zone (routing)
2. point_in_polygon_tool → Check hundreds of addresses (geometric)1. Does it require routing, roads, or travel times?
YES → Use routing API (directions, matrix, isochrone, optimization)
NO → Continue
2. Does it require traffic awareness?
YES → Use directions_tool or isochrone_tool with traffic profile
NO → Continue
3. Is it a geometric/spatial operation?
- Distance between points (straight-line) → distance_tool
- Point containment → point_in_polygon_tool
- Area calculation → area_tool
- Buffer/zone → buffer_tool
- Direction/bearing → bearing_tool
- Geometric center → centroid_tool
- Bounding box → bounding_box_tool
- Simplification → simplify_tool
4. Is it a search/discovery operation?
YES → Use search tools (search_and_geocode, category_search)const route = data.routes[0];
// GOOD — meters / seconds from the API
stats.textContent =
`Distance ${(route.distance / 1000).toFixed(2)} km · ` + `Duration ${Math.round(route.duration / 60)} min`;
// BAD — cosmetic labels or hardcoded ETAs that look like a working demo
// "Len 0.00 km · Time 2 min" / Math.round(120/60)// GOOD — three travel-time bands
`contours_minutes=15,30,60`;
// BAD — a single contour when the UX needs 15 / 30 / 60
`contours_minutes=30`;