{
  "q": "pizza",
  "proximity": {
    "longitude": -122.4194,
    "latitude": 37.7749
  }
}

{
  "q": "hotel",
  "bbox": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]
}

{
  "q": "Paris",
  "country": ["FR"] // ISO 3166 alpha-2 codes
}

// Only POIs and addresses, no cities
{"q": "Paris", "types": ["poi", "address"]}
// Returns Paris Hotel, Paris Street, not Paris, France

// Only places (cities/regions)
{"q": "Paris", "types": ["place"]}
// Returns Paris, France; Paris, Texas; etc.

{
  "q": "lunch",
  "poi_category": ["restaurant", "cafe"],
  "proximity": { "longitude": -122.4194, "latitude": 37.7749 }
}

{
  "category": "food_and_drink",
  "poi_category_exclusions": ["bar", "nightclub"]
}

// User types "starb"
{ "q": "starb", "auto_complete": true }
// Returns: Starbucks, Starboard Tavern, etc.

{
  "q": "grocery stores",
  "proximity": { "longitude": -122.4194, "latitude": 37.7749 },
  "eta_type": "navigation",
  "navigation_profile": "driving",
  "origin": { "longitude": -122.4194, "latitude": 37.7749 }
}

1. Blue Bottle Coffee
   Address: 66 Mint St, San Francisco, CA
   Coordinates: 37.7825, -122.4052
   Type: poi

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {"type": "Point", "coordinates": [-122.4052, 37.7825]},
    "properties": {"name": "Blue Bottle Coffee", ...}
  }]
}

{
  "q": "東京タワー",
  "language": "ja"
}
// Returns results in Japanese

1. Get user's location (from app/browser)
2. Use category_search_tool:
   - category: "coffee_shop"
   - proximity: user's coordinates
   - limit: 10

1. Use search_and_geocode_tool:
   - q: "Starbucks"
   - proximity: Seattle coordinates
   - country: ["US"]
2. Or if need strict boundary:
   - bbox: Seattle city bounds

Use search_and_geocode_tool:
- q: "1600 Pennsylvania Ave, Washington DC"
- types: ["address"]  // Focus on addresses
- country: ["US"]     // Narrow to US

1. Geocode "downtown Portland" → get center point
2. Define downtown bbox (or use 1-2 mile radius)
3. Use category_search_tool:
   - category: "hotel"
   - bbox: downtown bounds (or proximity + filter by distance)
   - limit: 25  // Get comprehensive list

Use reverse_geocode_tool:
- longitude: -122.4194
- latitude: 37.7749
- types: ["address"]  // Get address (can also use place, locality, postcode, etc.)

1. Get route geometry from directions_tool
2. Create bbox around route (use bounding_box_tool)
3. Use category_search_tool:
   - category: "gas_station"
   - bbox: route bounding box
4. Filter results to those within X meters of route (use distance_tool)

Use category_search_tool:
- category: "ramen_restaurant" (or "restaurant")
- language: "ja"
- proximity: user location

// BAD
category_search_tool({ category: 'starbucks' });
// "starbucks" is not a category, returns error

// GOOD
search_and_geocode_tool({ q: 'Starbucks' });

// BAD
search_and_geocode_tool({ q: 'coffee shops' });
// Less precise, may return unrelated results

// GOOD
category_search_tool({ category: 'coffee_shop' });

// BAD - Results may be anywhere globally
category_search_tool({ category: 'restaurant' });

// GOOD - Biased to user location
category_search_tool({
  category: 'restaurant',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

// BAD - Hard boundary may exclude good nearby results
search_and_geocode_tool({
  q: 'pizza',
  bbox: [-122.42, 37.77, -122.41, 37.78] // Tiny box
});

// GOOD - Bias toward point, but flexible
search_and_geocode_tool({
  q: 'pizza',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

// BAD - Costs API quota for routing calculations
search_and_geocode_tool({
  q: 'museums',
  eta_type: 'navigation',
  navigation_profile: 'driving'
});
// User didn't ask for travel time!

// GOOD - Only add ETA when needed
search_and_geocode_tool({ q: 'museums' });
// If user asks "how long to get there?", then add ETA

// BAD - Overwhelming for simple dropdown
category_search_tool({
  category: 'restaurant',
  limit: 25
});
// Returns 25 restaurants for a 5-item dropdown

// GOOD - Match UI needs
category_search_tool({
  category: 'restaurant',
  limit: 5
});

// GOOD
1. User enters "Seattle"
2. Geocode "Seattle" → (lng, lat)
3. Use those coordinates for multiple category searches
4. Cache coordinates for session

// BAD
1. Geocode "Seattle" for coffee search
2. Geocode "Seattle" again for restaurant search
3. Geocode "Seattle" again for hotel search

1. category_search_tool → Get POIs
2. distance_tool (offline) → Calculate distances
3. bearing_tool (offline) → Get directions

1. category_search_tool({category: "hospital", proximity: user_location})
   → Returns 10 hospitals with coordinates
2. distance_tool(user_location, each_hospital)
   → Calculate exact distances offline
3. Sort by distance

1. search_and_geocode_tool({q: "Space Needle"})
   → Get destination coordinates
2. directions_tool({from: user_location, to: space_needle_coords})
   → Get turn-by-turn directions

1. search_and_geocode_tool({q: "warehouse"})
   → Get warehouse coordinates
2. isochrone_tool({coordinates: warehouse, time: 30, profile: "driving"})
   → Get 30-minute delivery zone polygon
3. point_in_polygon_tool(customer_address, delivery_zone)
   → Check if customer is in delivery zone

1. category_search_tool({category: "restaurant", limit: 10})
   → Get restaurant coordinates
2. static_map_image_tool({
     markers: restaurant_coordinates,
     auto_fit: true
   })
   → Create map image showing all restaurants

1. category_search_tool({category: "taco"}) → No results
2. Check: Is "taco" a valid category?
   → Use category_list_tool → See "mexican_restaurant" is valid
3. Retry: category_search_tool({category: "mexican_restaurant"}) → Success

resource_reader_tool({uri: "mapbox://categories"})

User query contains...

→ Specific name/brand (Starbucks, Empire State Building)
  → search_and_geocode_tool

→ Generic category/plural (coffee shops, museums, any restaurant)
  → category_search_tool

→ Coordinates → Address
  → reverse_geocode_tool

→ Address → Coordinates
  → search_and_geocode_tool with types: ["address"]