Update to Mapbox

{
  "description": "Expert guidance on choosing the right Mapbox search tool and parameters for geocoding, POI search, and location discovery",
  "included_files": [
    {
      "relative_path": "evals/evals.json",
      "size_in_bytes": 1635
    },
    {
      "relative_path": "references/advanced-params.md",
      "size_in_bytes": 2929
    },
    {
      "relative_path": "references/optimization-combining.md",
      "size_in_bytes": 4376
    },
    {
      "relative_path": "references/workflows.md",
      "size_in_bytes": 2608
    }
  ],
  "name": "mapbox-search-patterns",
  "skill_md_contents": "---\nname: mapbox-search-patterns\ndescription: Expert guidance on choosing the right Mapbox search tool and parameters for geocoding, POI search, and location discovery\n---\n\n# Mapbox Search Patterns Skill\n\nExpert guidance for AI assistants on using Mapbox search tools effectively. Covers tool selection, parameter optimization, and best practices for geocoding, POI search, and location discovery.\n\n## Available Search Tools\n\n### 1. search_and_geocode_tool\n\n**Best for:** Specific places, addresses, brands, named locations\n\n**Use when query contains:**\n\n- Specific names: \"Starbucks on 5th Avenue\", \"Empire State Building\"\n- Brand names: \"McDonald's\", \"Whole Foods\"\n- Addresses: \"123 Main Street, Seattle\", \"1 Times Square\"\n- Chain stores: \"Target\"\n- Cities/places: \"San Francisco\", \"Portland\"\n\n**Don't use for:** Generic categories (\"coffee shops\", \"museums\")\n\n### 2. category_search_tool\n\n**Best for:** Generic place types, categories, plural queries\n\n**Use when query contains:**\n\n- Generic types: \"coffee shops\", \"restaurants\", \"gas stations\"\n- Plural forms: \"museums\", \"hotels\", \"parks\"\n- Is-a phrases: \"any coffee shop\", \"all restaurants\", \"nearby pharmacies\"\n- Industry terms: \"electric vehicle chargers\", \"ATMs\"\n\n**Don't use for:** Specific names or brands\n\n### 3. reverse_geocode_tool\n\n**Best for:** Converting coordinates to addresses, cities, towns, postcodes\n\n**Use when:**\n\n- Have GPS coordinates, need human-readable address\n- Need to identify what's at a specific location\n- Converting user location to address\n\n## Tool Selection Decision Matrix\n\n| User Query                      | Tool                    | Reasoning                |\n| ------------------------------- | ----------------------- | ------------------------ |\n| \"Find Starbucks on Main Street\" | search_and_geocode_tool | Specific brand name      |\n| \"Find coffee shops nearby\"      | category_search_tool    | Generic category, plural |\n| \"What's at 37.7749, -122.4194?\" | reverse_geocode_tool    | Coordinates to address   |\n| \"Empire State Building\"         | search_and_geocode_tool | Specific named POI       |\n| \"hotels in downtown Seattle\"    | category_search_tool    | Generic type + location  |\n| \"Target store locations\"        | search_and_geocode_tool | Brand name (even plural) |\n| \"any restaurant near me\"        | category_search_tool    | Generic + \"any\" phrase   |\n| \"123 Main St, Boston, MA\"       | search_and_geocode_tool | Specific address         |\n| \"electric vehicle chargers\"     | category_search_tool    | Industry category        |\n| \"McDonald's\"                    | search_and_geocode_tool | Brand name               |\n\n## Parameter Guidance\n\n### Proximity vs Bbox vs Country\n\n**Three ways to spatially constrain search results:**\n\n#### 1. proximity (STRONGLY RECOMMENDED)\n\n**What it does:** Biases results toward a location, but doesn't exclude distant matches\n\n**Use when:**\n\n- User says \"near me\", \"nearby\", \"close to\"\n- Have a reference point but want some flexibility\n- Want results sorted by relevance to a point\n\n**Example:**\n\n```json\n{\n  \"q\": \"pizza\",\n  \"proximity\": {\n    \"longitude\": -122.4194,\n    \"latitude\": 37.7749\n  }\n}\n```\n\n**Why this works:** API returns SF pizza places first, but might include famous NYC pizzerias if highly relevant\n\n**Critical:** Always set proximity when you have a reference location! Without it, results are IP-based or global.\n\n#### 2. bbox (Bounding Box)\n\n**What it does:** Hard constraint - ONLY returns results within the box\n\n**Use when:**\n\n- User specifies an area: \"in downtown\", \"within this neighborhood\"\n- Have a defined service area\n- Need to guarantee results are within bounds\n\n**Example:**\n\n```json\n{\n  \"q\": \"hotel\",\n  \"bbox\": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]\n}\n```\n\n**Why this works:** Guarantees all hotels are within SF's downtown area\n\n**Watch out:** Too small = no results; too large = irrelevant results\n\n#### 3. country\n\n**What it does:** Limits results to specific countries\n\n**Use when:**\n\n- User specifies country: \"restaurants in France\"\n- Building country-specific features\n- Need to respect regional boundaries\n- Or it is otherwise clear they want results within a specific country\n\n**Example:**\n\n```json\n{\n  \"q\": \"Paris\",\n  \"country\": [\"FR\"] // ISO 3166 alpha-2 codes\n}\n```\n\n**Why this works:** Finds Paris, France (not Paris, Texas)\n\n**Can combine:** `proximity` + `country` + `bbox` or any combination of the three\n\n### Decision Matrix: Spatial Filters\n\n| Scenario                           | Use                                 | Why                               |\n| ---------------------------------- | ----------------------------------- | --------------------------------- |\n| \"Find coffee near me\"              | proximity                           | Bias toward user location         |\n| \"Coffee shops in downtown Seattle\" | proximity + bbox                    | Center on downtown, limit to area |\n| \"Hotels in France\"                 | country                             | Hard country boundary             |\n| \"Best pizza in San Francisco\"      | proximity + country [\"US\"]          | Bias to SF, limit to US           |\n| \"Gas stations along this route\"    | bbox around route                   | Hard constraint to route corridor |\n| \"Restaurants within 5 miles\"       | proximity (then filter by distance) | Bias nearby, filter results       |\n\n### Setting limit Parameter\n\n**category_search_tool only** (1-25, default 10)\n\n| Use Case              | Limit | Reasoning               |\n| --------------------- | ----- | ----------------------- |\n| Quick suggestions     | 5     | Fast, focused results   |\n| Standard list         | 10    | Default, good balance   |\n| Comprehensive search  | 25    | Maximum allowed         |\n| Map visualization     | 25    | Show all nearby options |\n| Dropdown/autocomplete | 5     | Don't overwhelm UI      |\n\n**Performance tip:** Lower limits = faster responses\n\n### types Parameter (search_and_geocode_tool)\n\n**Filter by feature type:**\n\n| Type       | What It Includes                           | Use When                          |\n| ---------- | ------------------------------------------ | --------------------------------- |\n| `poi`      | Points of interest (businesses, landmarks) | Looking for POIs, not addresses   |\n| `address`  | Street addresses                           | Need specific address             |\n| `place`    | Cities, neighborhoods, regions             | Looking for area/region           |\n| `street`   | Street names without numbers               | Need street, not specific address |\n| `postcode` | Postal codes                               | Searching by ZIP/postal code      |\n| `district` | Districts, neighborhoods                   | Area-based search                 |\n| `locality` | Towns, villages                            | Municipality search               |\n| `country`  | Country names                              | Country-level search              |\n\n**Example combinations:**\n\n```json\n// Only POIs and addresses, no cities\n{\"q\": \"Paris\", \"types\": [\"poi\", \"address\"]}\n// Returns Paris Hotel, Paris Street, not Paris, France\n\n// Only places (cities)\n{\"q\": \"Paris\", \"types\": [\"place\"]}\n// Returns Paris, France; Paris, Texas; etc.\n```\n\n**Default behavior:** All types included (usually what you want)\n\n### auto_complete Parameter (search_and_geocode_tool)\n\n**What it does:** Enables partial/fuzzy matching\n\n| Setting           | Behavior                     | Use When                      |\n| ----------------- | ---------------------------- | ----------------------------- |\n| `true`            | Matches partial words, typos | User typing in real-time      |\n| `false` (default) | Exact matching               | Final query, not autocomplete |\n\n**Example:**\n\n<!-- cspell:disable -->\n\n```json\n// User types \"starb\"\n{ \"q\": \"starb\", \"auto_complete\": true }\n// Returns: Starbucks, Starboard Tavern, etc.\n```\n\n**Use for:**\n\n- Search-as-you-type interfaces\n- Handling typos (\"mcdonalds\" -> McDonald's)\n<!-- cspell:enable -->\n- Incomplete queries\n\n**Don't use for:**\n\n- Final/submitted queries (less precise)\n- When you need exact matches\n\n## Anti-Patterns to Avoid\n\n### Don't: Use category_search for brands\n\n```javascript\n// BAD\ncategory_search_tool({ category: 'starbucks' });\n// \"starbucks\" is not a category, returns error\n\n// GOOD\nsearch_and_geocode_tool({ q: 'Starbucks' });\n```\n\n### Don't: Use search_and_geocode for generic categories\n\n```javascript\n// BAD\nsearch_and_geocode_tool({ q: 'coffee shops' });\n// Less precise, may return unrelated results\n\n// GOOD\ncategory_search_tool({ category: 'coffee_shop' });\n```\n\n### Don't: Forget proximity for local searches\n\n```javascript\n// BAD - Results may be anywhere globally\ncategory_search_tool({ category: 'restaurant' });\n\n// GOOD - Biased to user location\ncategory_search_tool({\n  category: 'restaurant',\n  proximity: { longitude: -122.4194, latitude: 37.7749 }\n});\n```\n\n### Don't: Geocode ambiguous place names without proximity (REST too)\n\nThis applies to Mapbox Geocoding API v5 / Search Box in browser apps — not only MCP tools.\n\n```javascript\n// BAD — limit=1 without proximity can resolve \"Lincoln Memorial\" to Illinois\nfetch(`https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json?access_token=${token}&limit=1`);\n\n// GOOD — bias to map center (and optional bbox)\nfetch(\n  `https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(q)}.json` +\n    `?access_token=${token}&proximity=-77.0369,38.9072&bbox=-77.15,38.79,-76.90,38.99&limit=1`\n);\n```\n\nAlso debounce search inputs (`clearTimeout` + `setTimeout`) so every keystroke does not fire a geocode.\n\n### Don't: Use bbox when you mean proximity\n\n```javascript\n// BAD - Hard boundary may exclude good nearby results\nsearch_and_geocode_tool({\n  q: 'pizza',\n  bbox: [-122.42, 37.77, -122.41, 37.78] // Tiny box\n});\n\n// GOOD - Bias toward point, but flexible\nsearch_and_geocode_tool({\n  q: 'pizza',\n  proximity: { longitude: -122.4194, latitude: 37.7749 }\n});\n```\n\n### Don't: Request ETA unnecessarily\n\n```javascript\n// BAD - Costs API quota for routing calculations\nsearch_and_geocode_tool({\n  q: 'museums',\n  eta_type: 'navigation',\n  navigation_profile: 'driving'\n});\n// User didn't ask for travel time!\n\n// GOOD - Only add ETA when needed\nsearch_and_geocode_tool({ q: 'museums' });\n// If user asks \"how long to get there?\", then add ETA\n```\n\n### Don't: Set limit too high for UI display\n\n```javascript\n// BAD - Overwhelming for simple dropdown\ncategory_search_tool({\n  category: 'restaurant',\n  limit: 25\n});\n// Returns 25 restaurants for a 5-item dropdown\n\n// GOOD - Match UI needs\ncategory_search_tool({\n  category: 'restaurant',\n  limit: 5\n});\n```\n\n## Quick Reference\n\n### Tool Selection Flowchart\n\n```\nUser query contains...\n\n-> Specific name/brand (Starbucks, Empire State Building)\n  -> search_and_geocode_tool\n\n-> Generic category/plural (coffee shops, museums, any restaurant)\n  -> category_search_tool\n\n-> Coordinates -> Address\n  -> reverse_geocode_tool\n\n-> Address -> Coordinates\n  -> search_and_geocode_tool with types: [\"address\"]\n```\n\n### Essential Parameters Checklist\n\n**For local searches, ALWAYS set:**\n\n- `proximity` (or bbox if strict boundary needed)\n\n**For category searches, consider:**\n\n- `limit` (match UI needs)\n- `format` (json_string if plotting on map)\n\n**For disambiguation, use:**\n\n- `country` (when geographic context matters)\n- `types` (when feature type matters)\n\n**For travel-time ranking:**\n\n- `eta_type`, `navigation_profile`, `origin` (costs API quota)\n\n## Common Mistakes\n\n1. **Forgetting proximity** -> Results are global/IP-based (or wrong state for ambiguous memorial/park names)\n2. **Using wrong tool** -> category_search for \"Starbucks\" (use search_and_geocode)\n3. **Invalid category** -> Check category_list first\n4. **Bbox too small** -> No results; use proximity instead\n5. **Requesting ETA unnecessarily** -> Adds API cost\n6. **Limit too high for UI** -> Overwhelming user\n7. **Not filtering types** -> Get cities when you want POIs\n8. **No debounce on typeahead** -> Quota burn and racy UI\n\n## Reference Files\n\nLoad these for deeper guidance on specific topics:\n\n- **`references/advanced-params.md`** — poi_category, ETA, format, and language parameters\n- **`references/workflows.md`** — Common patterns: Near Me, Branded, Geocoding, Category+Area, Reverse, Route-Based, Multilingual\n- **`references/optimization-combining.md`** — Performance optimization, combining tools, handling no results, category list resource\n"
}