Expert 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.
Fetches mapbox-search-patterns from mapbox/mapbox-agent-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/mapbox-search-patterns
Restart Cursor to activate mapbox-search-patterns. Access via /mapbox-search-patterns in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
Expert 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.
Available Search Tools
1. search_and_geocode_tool
Best for: Specific places, addresses, brands, named locations
Use when query contains:
Specific names: "Starbucks on 5th Avenue", "Empire State Building"
Brand names: "McDonald's", "Whole Foods"
Addresses: "123 Main Street, Seattle", "1 Times Square"
Chain stores: "Target"
Cities/places: "San Francisco", "Portland"
Don't use for: Generic categories ("coffee shops", "museums")
2. category_search_tool
Best for: Generic place types, categories, plural queries
Why this works: Guarantees all hotels are within SF's downtown area
Watch out: Too small = no results; too large = irrelevant results
3. country
What it does: Limits results to specific countries
Use when:
User specifies country: "restaurants in France"
Building country-specific features
Need to respect regional boundaries
Or it is otherwise clear they want results within a specific country
Example:
{"q":"Paris","country":["FR"]// ISO 3166 alpha-2 codes}
Why this works: Finds Paris, France (not Paris, Texas)
Can combine:proximity + country + bbox or any combination of the three
Decision Matrix: Spatial Filters
Scenario
Use
Why
"Find coffee near me"
proximity
Bias toward user location
"Coffee shops in downtown Seattle"
proximity + bbox
Center on downtown, limit to area
"Hotels in France"
country
Hard country boundary
"Best pizza in San Francisco"
proximity + country ["US"]
Bias to SF, limit to US
"Gas stations along this route"
bbox around route
Hard constraint to route corridor
"Restaurants within 5 miles"
proximity (then filter by distance)
Bias nearby, filter results
Setting limit Parameter
category_search_tool only (1-25, default 10)
Use Case
Limit
Reasoning
Quick suggestions
5
Fast, focused results
Standard list
10
Default, good balance
Comprehensive search
25
Maximum allowed
Map visualization
25
Show all nearby options
Dropdown/autocomplete
5
Don't overwhelm UI
Performance tip: Lower limits = faster responses
types Parameter (search_and_geocode_tool)
Filter by feature type:
Type
What It Includes
Use When
poi
Points of interest (businesses, landmarks)
Looking for POIs, not addresses
address
Street addresses
Need specific address
place
Cities, neighborhoods, regions
Looking for area/region
street
Street names without numbers
Need street, not specific address
postcode
Postal codes
Searching by ZIP/postal code
district
Districts, neighborhoods
Area-based search
locality
Towns, villages
Municipality search
country
Country names
Country-level search
Example combinations:
// Only POIs and addresses, no cities{"q":"Paris","types":["poi","address"]}// Returns Paris Hotel, Paris Street, not Paris, France// Only places (cities){"q":"Paris","types":["place"]}// Returns Paris, France; Paris, Texas; etc.
Default behavior: All types included (usually what you want)
auto_complete Parameter (search_and_geocode_tool)
What it does: Enables partial/fuzzy matching
Setting
Behavior
Use When
true
Matches partial words, typos
User typing in real-time
false (default)
Exact matching
Final query, not autocomplete
Example:
// User types "starb"{"q":"starb","auto_complete":true}// Returns: Starbucks, Starboard Tavern, etc.
Use for:
Search-as-you-type interfaces
Handling typos ("mcdonalds" -> McDonald's)
Incomplete queries
Don't use for:
Final/submitted queries (less precise)
When you need exact matches
Anti-Patterns to Avoid
Don't: Use category_search for brands
// BADcategory_search_tool({category:'starbucks'});// "starbucks" is not a category, returns error// GOODsearch_and_geocode_tool({q:'Starbucks'});
Don't: Use search_and_geocode for generic categories
// BADsearch_and_geocode_tool({q:'coffee shops'});// Less precise, may return unrelated results// GOODcategory_search_tool({category:'coffee_shop'});
Don't: Forget proximity for local searches
// BAD - Results may be anywhere globallycategory_search_tool({category:'restaurant'});// GOOD - Biased to user locationcategory_search_tool({category:'restaurant',proximity:{longitude:-122.4194,latitude:37.7749}});
Don't: Use bbox when you mean proximity
// BAD - Hard boundary may exclude good nearby resultssearch_and_geocode_tool({q:'pizza',bbox:[-122.42,37.77,-122.41,37.78]// Tiny box});// GOOD - Bias toward point, but flexiblesearch_and_geocode_tool({q:'pizza',proximity:{longitude:-122.4194,latitude:37.7749}});
Don't: Request ETA unnecessarily
// BAD - Costs API quota for routing calculationssearch_and_geocode_tool({q:'museums',eta_type:'navigation',navigation_profile:'driving'});// User didn't ask for travel time!// GOOD - Only add ETA when neededsearch_and_geocode_tool({q:'museums'});// If user asks "how long to get there?", then add ETA
Don't: Set limit too high for UI display
// BAD - Overwhelming for simple dropdowncategory_search_tool({category:'restaurant',limit:25});// Returns 25 restaurants for a 5-item dropdown// GOOD - Match UI needscategory_search_tool({category
✓
Make data-driven prioritization decisions faster
Stakeholder Communication
Draft PRDs, status updates, and stakeholder presentations
›Access to product documentation and roadmap tools (Jira, Notion, etc.)
›Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
›Stakeholder contact information and communication channels
Time Estimate
30-60 minutes to see productivity improvements
Steps
1Install product management skill
2Start with user story generation for known feature
3Progress to competitive analysis: research 2-3 competitors
4Use for roadmap prioritization: apply RICE/ICE scoring
5Draft stakeholder communications and refine based on feedback
6Build template library for recurring PM tasks
7Share effective prompts with product team
Common Pitfalls
⚠Not validating competitive research—verify facts before sharing
⚠Accepting user stories without involving engineering team
⚠Over-relying on frameworks without qualitative judgment
⚠Not customizing outputs to company culture and communication style
⚠Skipping stakeholder validation of generated requirements
Best Practices
✓ Do
+Validate research and competitive analysis with real data
+Collaborate with engineering when generating technical requirements
+Customize frameworks and templates to your company context
+Use skill for first drafts, refine with stakeholder input
+Document successful prompt patterns for PM tasks
+Combine AI efficiency with human judgment and intuition
✗ Don't
−Don't publish competitive analysis without fact-checking
−Don't finalize user stories without engineering review
−Don't make prioritization decisions solely on AI scoring
−Don't skip customer validation of generated requirements
−Don't ignore company-specific context and culture
💡 Pro Tips
★Provide context: company goals, constraints, customer feedback
★Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
★Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
★Use skill for 70% generation + 30% customization to company needs
When to Use This
✓ Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
✗ Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path
1Basic: user stories, feature specs, status updates
