--- name: mapbox-geospatial-operations description: Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs ---

# Mapbox Geospatial Operations Skill

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.

## Core Principle: Problem Type Determines Tool Choice

The Mapbox MCP Server provides two categories of geospatial tools:

1. **Offline Geometric Tools** - Use Turf.js for pure geometric/spatial calculations 2. **Routing & Navigation APIs** - Use Mapbox APIs when you need real-world routing, traffic, or travel times

**The key question: What does the problem actually require?**

### Decision Framework

| 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 |

## Decision Matrices by Use Case

### Distance Calculations

**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?"**

- As the crow flies → `distance_tool` (10 calculations, instant) - As the crow drives → `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?

### Proximity and Containment

**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?"**

1. Create zone → `isochrone_tool` (routing API - need travel time) 2. Check addresses → `point_in_polygon_tool` (geometric - 200 instant checks)

**Key insight:** Routing for creating travel-time zones, geometric for containment checks

### Routing and Navigation

**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"**

- Need turn-by-turn → `directions_tool` - Just need to know "it's northeast" → `bearing_tool`

**Key insight:** Routing tools for actual navigation, geometric tools for directional info

### Area and Shape Operations

**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"**

- 5km radius → `buffer_tool` (geometric circles) - "What customers can reach in 15 min?" → `isochrone_tool` (routing-based)

**Key insight:** Geometric tools for distance-based zones, routing tools for time-based zones

## Performance and Scale Considerations

### When Volume Affects Tool Choice

**Small operations (< 100 calculations):**

- Geometric tools: Instant, iterate freely - Routing APIs: Fast enough for most uses

**Medium operations (100-1,000 calculations):**

- Geometric tools: Still fast, no concerns - Routing APIs: Consider batch operations (matrix_tool)

**Large operations (> 1,000 calculations):**

- Geometric tools: May need optimization but still fast - Routing APIs: Definitely use batch tools (matrix_tool handles up to 25×25)

**Key insight:** Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency

### Real-Time vs Batch

| 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`).

## Common Scenarios and Optimal Approaches

### Scenario 1: Store Locator

**User: "Find the closest store and show 5km coverage"**

**Optimal approach:**

1. Search stores → `category_search_tool` (returns distances automatically) 2. Create coverage zone → `buffer_tool` (5km geometric circle) 3. Visualize → `static_map_image_tool`

**Why:** Search already gives distances; geometric buffer for simple radius

### Scenario 2: Delivery Route Optimization

**User: "Optimize delivery to 8 addresses / stops"**

**Optimal approach:**

1. **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. 2. **Optimize route** → `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.

### Scenario 3: Service Area Validation

**User: "Which of these 200 addresses can we deliver to in 30 minutes?"**

**Optimal approach:**

1. Create delivery zone → `isochrone_tool` (30-minute driving) 2. Check each address → `point_in_polygon_tool` (200 geometric checks)

**Why:** Routing for accurate travel-time zone, geometric for fast containment checks

### Scenario 4: GPS Trace Analysis

**User: "How long was this bike ride?"**

**Optimal approach:**

1. Clean GPS trace → `map_matching_tool` (snap to bike paths) 2. Get distance → Use API response or calculate with `distance_tool`

**Why:** Need road/path matching; distance calculation either way works

### Scenario 5: Coverage Analysis

**User: "What's our total service area?"**

**Optimal approach:**

1. Create buffers around each location → `buffer_tool` 2. Calculate total area → `area_tool` 3. Or, if time-based → `isochrone_tool` for each location

**Why:** Geometric for distance-based coverage, routing for time-based

## Anti-Patterns: Using the Wrong Tool Type

### ❌ Don't: Use geometric tools for routing questions

```javascript // WRONG: User asks "how long to drive there?" distance_tool({ from: A, to: B }); // Returns 10km as the crow flies, but actual drive is 15km

// CORRECT: Need routing for driving distance directions_tool({ coordinates: [ { longitude: A[0], latitude: A[1] }, { longitude: B[0], latitude: B[1] } ], routing_profile: 'mapbox/driving' }); // Returns actual road distance and drive time as the crow drives ```

**Why wrong:** As the crow flie

--- name: mapbox-geospatial-operations description: Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs ---

# Mapbox Geospatial Operations Skill

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.

## Core Principle: Problem Type Determines Tool Choice

The Mapbox MCP Server provides two categories of geospatial tools:

1. **Offline Geometric Tools** - Use Turf.js for pure geometric/spatial calculations 2. **Routing & Navigation APIs** - Use Mapbox APIs when you need real-world routing, traffic, or travel times

**The key question: What does the problem actually require?**

### Decision Framework

| 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 |

## Decision Matrices by Use Case

### Distance Calculations

**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?"**

- As the crow flies → `distance_tool` (10 calculations, instant) - As the crow drives → `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?

### Proximity and Containment

**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?"**

1. Create zone → `isochrone_tool` (routing API - need travel time) 2. Check addresses → `point_in_polygon_tool` (geometric - 200 instant checks)

**Key insight:** Routing for creating travel-time zones, geometric for containment checks

### Routing and Navigation

**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"**

- Need turn-by-turn → `directions_tool` - Just need to know "it's northeast" → `bearing_tool`

**Key insight:** Routing tools for actual navigation, geometric tools for directional info

### Area and Shape Operations

**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"**

- 5km radius → `buffer_tool` (geometric circles) - "What customers can reach in 15 min?" → `isochrone_tool` (routing-based)

**Key insight:** Geometric tools for distance-based zones, routing tools for time-based zones

## Performance and Scale Considerations

### When Volume Affects Tool Choice

**Small operations (< 100 calculations):**

- Geometric tools: Instant, iterate freely - Routing APIs: Fast enough for most uses

**Medium operations (100-1,000 calculations):**

- Geometric tools: Still fast, no concerns - Routing APIs: Consider batch operations (matrix_tool)

**Large operations (> 1,000 calculations):**

- Geometric tools: May need optimization but still fast - Routing APIs: Definitely use batch tools (matrix_tool handles up to 25×25)

**Key insight:** Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency

### Real-Time vs Batch

| 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`).

## Common Scenarios and Optimal Approaches

### Scenario 1: Store Locator

**User: "Find the closest store and show 5km coverage"**

**Optimal approach:**

1. Search stores → `category_search_tool` (returns distances automatically) 2. Create coverage zone → `buffer_tool` (5km geometric circle) 3. Visualize → `static_map_image_tool`

**Why:** Search already gives distances; geometric buffer for simple radius

### Scenario 2: Delivery Route Optimization

**User: "Optimize delivery to 8 addresses / stops"**

**Optimal approach:**

1. **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. 2. **Optimize route** → `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.

### Scenario 3: Service Area Validation

**User: "Which of these 200 addresses can we deliver to in 30 minutes?"**

**Optimal approach:**

1. Create delivery zone → `isochrone_tool` (30-minute driving) 2. Check each address → `point_in_polygon_tool` (200 geometric checks)

**Why:** Routing for accurate travel-time zone, geometric for fast containment checks

### Scenario 4: GPS Trace Analysis

**User: "How long was this bike ride?"**

**Optimal approach:**

1. Clean GPS trace → `map_matching_tool` (snap to bike paths) 2. Get distance → Use API response or calculate with `distance_tool`

**Why:** Need road/path matching; distance calculation either way works

### Scenario 5: Coverage Analysis

**User: "What's our total service area?"**

**Optimal approach:**

1. Create buffers around each location → `buffer_tool` 2. Calculate total area → `area_tool` 3. Or, if time-based → `isochrone_tool` for each location

**Why:** Geometric for distance-based coverage, routing for time-based

## Anti-Patterns: Using the Wrong Tool Type

### ❌ Don't: Use geometric tools for routing questions

```javascript // WRONG: User asks "how long to drive there?" distance_tool({ from: A, to: B }); // Returns 10km as the crow flies, but actual drive is 15km

// CORRECT: Need routing for driving distance directions_tool({ coordinates: [ { longitude: A[0], latitude: A[1] }, { longitude: B[0], latitude: B[1] } ], routing_profile: 'mapbox/driving' }); // Returns actual road distance and drive time as the crow drives ```

**Why wrong:** As the crow flie

--- name: mapbox-geospatial-operations description: Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs ---

# Mapbox Geospatial Operations Skill

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.

## Core Principle: Problem Type Determines Tool Choice

The Mapbox MCP Server provides two categories of geospatial tools:

1. **Offline Geometric Tools** - Use Turf.js for pure geometric/spatial calculations 2. **Routing & Navigation APIs** - Use Mapbox APIs when you need real-world routing, traffic, or travel times

**The key question: What does the problem actually require?**

### Decision Framework

| 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 |

## Decision Matrices by Use Case

### Distance Calculations

**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?"**

- As the crow flies → `distance_tool` (10 calculations, instant) - As the crow drives → `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?

### Proximity and Containment

**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?"**

1. Create zone → `isochrone_tool` (routing API - need travel time) 2. Check addresses → `point_in_polygon_tool` (geometric - 200 instant checks)

**Key insight:** Routing for creating travel-time zones, geometric for containment checks

### Routing and Navigation

**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"**

- Need turn-by-turn → `directions_tool` - Just need to know "it's northeast" → `bearing_tool`

**Key insight:** Routing tools for actual navigation, geometric tools for directional info

### Area and Shape Operations

**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"**

- 5km radius → `buffer_tool` (geometric circles) - "What customers can reach in 15 min?" → `isochrone_tool` (routing-based)

**Key insight:** Geometric tools for distance-based zones, routing tools for time-based zones

## Performance and Scale Considerations

### When Volume Affects Tool Choice

**Small operations (< 100 calculations):**

- Geometric tools: Instant, iterate freely - Routing APIs: Fast enough for most uses

**Medium operations (100-1,000 calculations):**

- Geometric tools: Still fast, no concerns - Routing APIs: Consider batch operations (matrix_tool)

**Large operations (> 1,000 calculations):**

- Geometric tools: May need optimization but still fast - Routing APIs: Definitely use batch tools (matrix_tool handles up to 25×25)

**Key insight:** Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency

### Real-Time vs Batch

| 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`).

## Common Scenarios and Optimal Approaches

### Scenario 1: Store Locator

**User: "Find the closest store and show 5km coverage"**

**Optimal approach:**

1. Search stores → `category_search_tool` (returns distances automatically) 2. Create coverage zone → `buffer_tool` (5km geometric circle) 3. Visualize → `static_map_image_tool`

**Why:** Search already gives distances; geometric buffer for simple radius

### Scenario 2: Delivery Route Optimization

**User: "Optimize delivery to 8 addresses / stops"**

**Optimal approach:**

1. **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. 2. **Optimize route** → `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.

### Scenario 3: Service Area Validation

**User: "Which of these 200 addresses can we deliver to in 30 minutes?"**

**Optimal approach:**

1. Create delivery zone → `isochrone_tool` (30-minute driving) 2. Check each address → `point_in_polygon_tool` (200 geometric checks)

**Why:** Routing for accurate travel-time zone, geometric for fast containment checks

### Scenario 4: GPS Trace Analysis

**User: "How long was this bike ride?"**

**Optimal approach:**

1. Clean GPS trace → `map_matching_tool` (snap to bike paths) 2. Get distance → Use API response or calculate with `distance_tool`

**Why:** Need road/path matching; distance calculation either way works

### Scenario 5: Coverage Analysis

**User: "What's our total service area?"**

**Optimal approach:**

1. Create buffers around each location → `buffer_tool` 2. Calculate total area → `area_tool` 3. Or, if time-based → `isochrone_tool` for each location

**Why:** Geometric for distance-based coverage, routing for time-based

## Anti-Patterns: Using the Wrong Tool Type

### ❌ Don't: Use geometric tools for routing questions

```javascript // WRONG: User asks "how long to drive there?" distance_tool({ from: A, to: B }); // Returns 10km as the crow flies, but actual drive is 15km

// CORRECT: Need routing for driving distance directions_tool({ coordinates: [ { longitude: A[0], latitude: A[1] }, { longitude: B[0], latitude: B[1] } ], routing_profile: 'mapbox/driving' }); // Returns actual road distance and drive time as the crow drives ```

**Why wrong:** As the crow flie

--- name: mapbox-geospatial-operations description: Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs ---

# Mapbox Geospatial Operations Skill

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.

## Core Principle: Problem Type Determines Tool Choice

The Mapbox MCP Server provides two categories of geospatial tools:

1. **Offline Geometric Tools** - Use Turf.js for pure geometric/spatial calculations 2. **Routing & Navigation APIs** - Use Mapbox APIs when you need real-world routing, traffic, or travel times

**The key question: What does the problem actually require?**

### Decision Framework

| 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 |

## Decision Matrices by Use Case

### Distance Calculations

**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?"**

- As the crow flies → `distance_tool` (10 calculations, instant) - As the crow drives → `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?

### Proximity and Containment

**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?"**

1. Create zone → `isochrone_tool` (routing API - need travel time) 2. Check addresses → `point_in_polygon_tool` (geometric - 200 instant checks)

**Key insight:** Routing for creating travel-time zones, geometric for containment checks

### Routing and Navigation

**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"**

- Need turn-by-turn → `directions_tool` - Just need to know "it's northeast" → `bearing_tool`

**Key insight:** Routing tools for actual navigation, geometric tools for directional info

### Area and Shape Operations

**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"**

- 5km radius → `buffer_tool` (geometric circles) - "What customers can reach in 15 min?" → `isochrone_tool` (routing-based)

**Key insight:** Geometric tools for distance-based zones, routing tools for time-based zones

## Performance and Scale Considerations

### When Volume Affects Tool Choice

**Small operations (< 100 calculations):**

- Geometric tools: Instant, iterate freely - Routing APIs: Fast enough for most uses

**Medium operations (100-1,000 calculations):**

- Geometric tools: Still fast, no concerns - Routing APIs: Consider batch operations (matrix_tool)

**Large operations (> 1,000 calculations):**

- Geometric tools: May need optimization but still fast - Routing APIs: Definitely use batch tools (matrix_tool handles up to 25×25)

**Key insight:** Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency

### Real-Time vs Batch

| 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`).

## Common Scenarios and Optimal Approaches

### Scenario 1: Store Locator

**User: "Find the closest store and show 5km coverage"**

**Optimal approach:**

1. Search stores → `category_search_tool` (returns distances automatically) 2. Create coverage zone → `buffer_tool` (5km geometric circle) 3. Visualize → `static_map_image_tool`

**Why:** Search already gives distances; geometric buffer for simple radius

### Scenario 2: Delivery Route Optimization

**User: "Optimize delivery to 8 addresses / stops"**

**Optimal approach:**

1. **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. 2. **Optimize route** → `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.

### Scenario 3: Service Area Validation

**User: "Which of these 200 addresses can we deliver to in 30 minutes?"**

**Optimal approach:**

1. Create delivery zone → `isochrone_tool` (30-minute driving) 2. Check each address → `point_in_polygon_tool` (200 geometric checks)

**Why:** Routing for accurate travel-time zone, geometric for fast containment checks

### Scenario 4: GPS Trace Analysis

**User: "How long was this bike ride?"**

**Optimal approach:**

1. Clean GPS trace → `map_matching_tool` (snap to bike paths) 2. Get distance → Use API response or calculate with `distance_tool`

**Why:** Need road/path matching; distance calculation either way works

### Scenario 5: Coverage Analysis

**User: "What's our total service area?"**

**Optimal approach:**

1. Create buffers around each location → `buffer_tool` 2. Calculate total area → `area_tool` 3. Or, if time-based → `isochrone_tool` for each location

**Why:** Geometric for distance-based coverage, routing for time-based

## Anti-Patterns: Using the Wrong Tool Type

### ❌ Don't: Use geometric tools for routing questions

```javascript // WRONG: User asks "how long to drive there?" distance_tool({ from: A, to: B }); // Returns 10km as the crow flies, but actual drive is 15km

// CORRECT: Need routing for driving distance directions_tool({ coordinates: [ { longitude: A[0], latitude: A[1] }, { longitude: B[0], latitude: B[1] } ], routing_profile: 'mapbox/driving' }); // Returns actual road distance and drive time as the crow drives ```

**Why wrong:** As the crow flie