Merge branch 'main' into compact-response-parameter

Author: mattpodwysocki

src/tools/category-search-tool/CategorySearchTool.ts

@@ -19,8 +19,26 @@ export class CategorySearchTool extends MapboxApiBasedTool<
   typeof CategorySearchResponseSchema
 > {
   name = 'category_search_tool';
-  description =
-    "Return all places that match a category (industry, amenity, or NAICS‑style code). Use when the user asks for a type of place, plural or generic terms like 'museums', 'coffee shops', 'electric‑vehicle chargers', or when the query includes is‑a phrases such as 'any', 'all', 'nearby'. Do not use when a unique name or brand is provided. Supports both JSON and text output formats.";
+  description = `Search for points of interest by category or type (restaurants, gas stations, hotels, ATMs, parking, coffee shops, pharmacies, museums, hospitals, etc.). Returns a list of nearby places matching the category with coordinates, names, addresses, and details.
+
+  Use this when:
+    - User asks for a type or category of place (plural/generic): "Where are the restaurants nearby?", "Show me all coffee shops"
+    - Browsing options: "What hotels are available downtown?", "Find gas stations along this route"
+    - Discovery queries: "What's around here?", "Show me all ATMs in this neighborhood"
+    - Generic searches with keywords like 'any', 'all', 'nearby', 'around', 'in this area'
+
+  Common use cases:
+    - Find all POIs by type: "Show me all pharmacies within 5 miles"
+    - Browse options: "What restaurants are near Times Square?"
+    - Amenity search: "Find EV charging stations nearby"
+    - Service discovery: "Where are the nearest hospitals?"
+    - Shopping: "Show me all grocery stores in downtown Seattle"
+
+  Difference from search_and_geocode_tool:
+    - Use category_search_tool for types/categories (e.g., "all restaurants", "coffee shops")
+    - Use search_and_geocode_tool for specific names/brands (e.g., "Starbucks on 5th Ave", "Empire State Building")
+
+  Supports both JSON and text output formats.`;
   annotations = {
     title: 'Category Search Tool',
     readOnlyHint: true,

src/tools/directions-tool/DirectionsTool.ts

@@ -21,8 +21,31 @@ export class DirectionsTool extends MapboxApiBasedTool<
   typeof DirectionsResponseSchema
 > {
   name = 'directions_tool';
-  description =
-    'Fetches directions from Mapbox API based on provided coordinates and direction method.';
+  description = `Calculate optimal routes and turn-by-turn directions (navigation) between two or more locations. Returns detailed driving, walking, or cycling instructions with route geometry (path), distance, duration, and estimated travel time (ETA).
+
+  Supports multiple routing modes:
+    - Driving routes with real-time traffic (car navigation, auto routing)
+    - Walking directions (pedestrian routes, on foot)
+    - Cycling routes (bike paths, bicycle-friendly roads)
+    - Multiple waypoints (road trip planning, multi-stop routes)
+
+  Common use cases:
+    - Get driving directions from point A to B: "How do I drive from LAX to Hollywood?"
+    - Calculate travel time and distance: "How long to walk from Central Park to Times Square?"
+    - Plan multi-stop routes: "Route from hotel to museum to restaurant to hotel"
+    - Compare route options: "Show me the fastest route avoiding tolls"
+    - Navigation with traffic: "Driving directions with current traffic conditions"
+
+  Returns:
+    - Turn-by-turn instructions
+    - Route geometry (GeoJSON path for mapping)
+    - Total distance and duration
+    - Step-by-step maneuvers
+
+  Related tools:
+    - Use matrix_tool for travel times between many locations
+    - Use isochrone_tool to see areas reachable within a time limit
+    - Use search_and_geocode_tool to convert addresses to coordinates first`;
   annotations = {
     title: 'Directions Tool',
     readOnlyHint: true,

src/tools/isochrone-tool/IsochroneTool.ts

@@ -16,11 +16,20 @@ export class IsochroneTool extends MapboxApiBasedTool<
   typeof IsochroneResponseSchema
 > {
   name = 'isochrone_tool';
-  description = `Computes areas that are reachable within a specified amount of time from a location, and returns the reachable regions as contours of Polygons or LineStrings in GeoJSON format that you can display on a map.
+  description = `Computes areas that are reachable within a specified amount of time or distance from a location (reachability analysis, coverage area, service area). Returns the reachable regions as contours of Polygons or LineStrings in GeoJSON format that you can display on a map.
+
   Common use cases:
     - Show a user how far they can travel in X minutes from their current location
     - Determine whether a destination is within a certain travel time threshold
-    - Compare travel ranges for different modes of transportation'`;
+    - Compare travel ranges for different modes of transportation (driving, walking, cycling)
+    - Visualize service coverage areas for businesses or facilities
+    - Analyze accessibility and reachability for logistics planning
+    - Find all areas within 30-minute drive time for delivery zones
+
+  Returns:
+    - GeoJSON contours showing reachable areas
+    - Multiple time/distance bands (e.g., 10, 20, 30 minutes)
+    - Visualizable polygons for mapping coverage`;
   annotations = {
     title: 'Isochrone Tool',
     readOnlyHint: true,

src/tools/matrix-tool/MatrixTool.ts

@@ -19,8 +19,29 @@ export class MatrixTool extends MapboxApiBasedTool<
   typeof MatrixResponseSchema
 > {
   name = 'matrix_tool';
-  description =
-    'Calculates travel times and distances between multiple points using Mapbox Matrix API.';
+  description = `Calculate travel times and distances between multiple origin and destination points (one-to-many, many-to-one, or many-to-many routing). Returns a distance/duration matrix showing travel time (ETA) and distance from each origin to each destination.
+
+  Common use cases:
+    - Logistics and route optimization: "Calculate travel times from warehouse to 10 delivery addresses"
+    - Find nearest location: "Which store location is closest to this customer?"
+    - Delivery time estimates: "How long to deliver from restaurant to multiple addresses?"
+    - Service area analysis: "Calculate distances from office to all branch locations"
+    - Multi-point comparison: "Compare travel times between 5 hotels and 3 attractions"
+
+  Supports:
+    - One-to-many: Single origin to multiple destinations
+    - Many-to-one: Multiple origins to single destination
+    - Many-to-many: Multiple origins to multiple destinations
+    - Different travel modes: driving (with traffic), walking, cycling
+
+  Returns:
+    - Matrix of travel times (durations) between all point pairs
+    - Matrix of distances between all point pairs
+    - Efficient bulk calculations for route optimization
+
+  Related tools:
+    - Use directions_tool for turn-by-turn directions for a single route
+    - Use isochrone_tool to visualize all areas reachable within a time limit`;
   annotations = {
     title: 'Matrix Tool',
     readOnlyHint: true,

src/tools/reverse-geocode-tool/ReverseGeocodeTool.ts

@@ -19,8 +19,30 @@ export class ReverseGeocodeTool extends MapboxApiBasedTool<
   typeof GeocodingResponseSchema
 > {
   name = 'reverse_geocode_tool';
-  description =
-    'Find addresses, cities, towns, neighborhoods, postcodes, districts, regions, and countries around a specified geographic coordinate pair. Converts geographic coordinates (longitude, latitude) into human-readable addresses or place names. Use limit=1 for best results. This tool cannot reverse geocode businesses, landmarks, historic sites, and other points of interest that are not of the types mentioned. Supports both JSON and text output formats.';
+  description = `Convert geographic coordinates (longitude, latitude) into human-readable addresses or place names (reverse geocoding). Returns addresses, cities, towns, neighborhoods, postal codes (zip codes), districts, regions, and countries for a specific coordinate pair.
+
+  Common use cases:
+    - "What address is at these coordinates?" - Get street address from GPS location
+    - "Where am I?" - Convert device location to readable address
+    - "What city is this?" - Identify city/town from coordinates
+    - "Get postal code for location" - Find zip code or postal code
+    - "Reverse geocode map click" - Display address when user clicks on map
+
+  Returns information about:
+    - Street addresses (house number and street name)
+    - Neighborhoods and districts
+    - Cities, towns, and villages
+    - Postal codes and zip codes
+    - States, provinces, and regions
+    - Countries
+
+  Note: Use limit=1 for best results (most relevant match). This tool cannot reverse geocode businesses, landmarks, historic sites, and other points of interest - it only returns administrative locations and addresses.
+
+  Related tools:
+    - Use search_and_geocode_tool for the opposite: convert addresses to coordinates (forward geocoding)
+    - Use search_and_geocode_tool to find businesses or POIs by name
+
+  Supports both JSON and text output formats.`;
   annotations = {
     title: 'Reverse Geocode Tool',
     readOnlyHint: true,

src/tools/search-and-geocode-tool/SearchAndGeocodeTool.ts

@@ -22,8 +22,25 @@ export class SearchAndGeocodeTool extends MapboxApiBasedTool<
   typeof SearchBoxResponseSchema
 > {
   name = 'search_and_geocode_tool';
-  description =
-    "Search for POIs, brands, chains, geocode cities, towns, addresses. Do not use for generic place types such as 'museums', 'coffee shops', 'tacos', etc, because category_search_tool is better for that. Setting a proximity point is strongly encouraged for more local results.";
+  description = `Search for specific points of interest (POIs), businesses, brands, landmarks, and convert addresses or place names to coordinates (geocoding). Returns detailed location information including coordinates (latitude/longitude), addresses, and place metadata.
+
+  Use this when:
+    - User specifies a particular place name, brand, or business (e.g., "Starbucks on 5th Avenue", "Empire State Building")
+    - Converting addresses to coordinates for mapping or routing
+    - Looking up specific landmarks, buildings, or locations by name
+    - Need precise location details for a named place
+
+  Common use cases:
+    - Geocode an address: "123 Main Street, Seattle, WA" → coordinates
+    - Find a specific business: "Find the nearest Tesla showroom"
+    - Locate landmarks: "Where is the Statue of Liberty?"
+    - Get coordinates for routing: "Get directions from Central Park to Times Square"
+
+  Related tools:
+    - Use category_search_tool for browsing all places by type (e.g., "all restaurants nearby", "show me gas stations")
+    - Use reverse_geocode_tool to convert coordinates back to addresses
+
+  Note: Do not use for generic place types like 'museums', 'coffee shops', 'tacos' - category_search_tool is better for that. Setting a proximity point is strongly encouraged for more local results.`;
   annotations = {
     title: 'Search and Geocode Tool',
     readOnlyHint: true,

src/tools/static-map-image-tool/StaticMapImageTool.ts

@@ -14,8 +14,33 @@ export class StaticMapImageTool extends MapboxApiBasedTool<
   typeof StaticMapImageInputSchema
 > {
   name = 'static_map_image_tool';
-  description =
-    'Generates a static map image from Mapbox Static Images API. Supports center coordinates, zoom level (0-22), image size (up to 1280x1280), various Mapbox styles, and overlays (markers, paths, GeoJSON). Returns PNG for vector styles, JPEG for raster-only styles.';
+  description = `Generate a static map image URL from Mapbox Static Images API. Creates a snapshot/thumbnail of a map location with optional markers, paths, and overlays. Returns a direct URL to the image (PNG or JPEG format), not an embedded image.
+
+  Common use cases:
+    - Create shareable map snapshots for reports or documentation
+    - Generate thumbnail previews of locations for listings or search results
+    - Embed map images in emails, PDFs, or presentations
+    - Show route overview as static image
+    - Create before/after comparison maps
+    - Display location context in non-interactive formats
+
+  Supports:
+    - Custom center coordinates and zoom level (0-22)
+    - Image dimensions up to 1280x1280 pixels
+    - Multiple map styles (streets, satellite, outdoors, dark, light, etc.)
+    - Markers with custom colors and labels
+    - Paths and polylines (routes, boundaries)
+    - GeoJSON overlays for complex shapes
+
+  Output format:
+    - Returns direct URL string to image file
+    - PNG format for vector styles
+    - JPEG format for raster/satellite styles
+    - URL can be embedded in HTML, shared, or downloaded
+
+  Related tools:
+    - Use directions_tool to get route geometry to display on static map
+    - Use search_and_geocode_tool to get coordinates for map center`;
   annotations = {
     title: 'Static Map Image Tool',
     readOnlyHint: true,

test/tools/README.md

@@ -0,0 +1,94 @@
+# Tool Description Testing
+
+This directory contains tests for validating tool description quality and semantic matching capabilities.
+
+## Test Suites
+
+### 1. Description Quality Tests (`description-quality.test.ts`)
+
+Validates that tool descriptions meet quality standards:
+
+- ✅ Minimum length (>200 characters)
+- ✅ Includes use cases and examples
+- ✅ Contains relevant keywords for semantic matching
+- ✅ Cross-references related tools
+- ✅ Follows consistent structure
+
+**Run:** `npm test -- test/tools/description-quality.test.ts`
+
+### 2. Description Baseline Tests (`description-baseline.test.ts`)
+
+Prevents regression of description quality over time:
+
+- ✅ Maintains minimum word/phrase counts per tool
+- ✅ Preserves semantic richness (vocabulary diversity)
+- ✅ Ensures domain-specific terminology
+- ✅ Validates consistent structure patterns
+
+**Run:** `npm test -- test/tools/description-baseline.test.ts`
+
+### 3. Semantic Tool Selection Tests (`semantic-tool-selection.test.ts`)
+
+**⚠️ Requires OpenAI API Key**
+
+Validates that tool descriptions work correctly with RAG-based semantic matching using OpenAI embeddings (text-embedding-3-small model).
+
+Tests query-to-tool matching:
+
+- ✅ "find coffee shops nearby" → `category_search_tool`
+- ✅ "where is Starbucks" → `search_and_geocode_tool`
+- ✅ "driving directions" → `directions_tool`
+- ✅ "areas reachable in 30 minutes" → `isochrone_tool`
+- ✅ Category vs specific place disambiguation
+- ✅ Semantic similarity thresholds (>0.5 for relevant tools)
+
+#### Running Semantic Tests
+
+**Local Development:**
+
+```bash
+export OPENAI_API_KEY="your-key-here"
+npm test -- test/tools/semantic-tool-selection.test.ts
+```
+
+**CI/CD:**
+Set `OPENAI_API_KEY` as a GitHub secret and tests will run automatically.
+
+**Without API Key:**
+Tests are automatically skipped if `OPENAI_API_KEY` is not set.
+
+## Test Philosophy
+
+These tests align with our RAG optimization goals:
+
+1. **Quality Tests** - Maintain description standards
+2. **Baseline Tests** - Prevent regressions over time
+3. **Semantic Tests** - Validate actual tool selection performance
+
+The semantic tests are the **core validation** that descriptions work as intended for RAG-based tool selection, while quality/baseline tests ensure consistency.
+
+## Expected Results
+
+After RAG-optimized descriptions (PR #78):
+
+- Average description length: ~1,260 characters
+- Vocabulary diversity: 44-52% unique words
+- Semantic similarity for relevant queries: >0.5
+
+## Updating Baselines
+
+If you intentionally improve descriptions beyond current baselines, update the thresholds in `description-baseline.test.ts`:
+
+```typescript
+const baselines: Record<
+  string,
+  { minLength: number; minWords: number; minPhrases: number }
+> = {
+  search_and_geocode_tool: {
+    minLength: 800, // Update if improved
+    minWords: 120,
+    minPhrases: 15
+  }
+  // ...
+};
+```