feat: add composite tools — explore-area, plan-route, compare-places

Three high-level tools that chain atomic tools internally:

- maps_explore_area: geocode → search-nearby (multi-type) → place-details
  "What's around Tokyo Tower?" → categorized results with details in 1 call

- maps_plan_route: geocode → distance-matrix → nearest-neighbor → directions
  "Visit these 5 places efficiently" → optimized route with legs in 1 call

- maps_compare_places: search-places → place-details → distance-matrix
  "Which ramen shop near Shibuya?" → comparison table in 1 call

Uses driving mode for route optimization (transit matrix returns nulls).
Handles directions failures gracefully (marks leg as "unknown").

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cablate

src/cli.ts

@@ -86,6 +86,9 @@ const EXEC_TOOLS = [
   "elevation",
   "timezone",
   "weather",
+  "explore-area",
+  "plan-route",
+  "compare-places",
 ] as const;
 
 async function execTool(toolName: string, params: any, apiKey: string): Promise<any> {
@@ -152,6 +155,18 @@ async function execTool(toolName: string, params: any, apiKey: string): Promise<
         params.forecastHours
       );
 
+    case "explore-area":
+    case "maps_explore_area":
+      return searcher.exploreArea(params);
+
+    case "plan-route":
+    case "maps_plan_route":
+      return searcher.planRoute(params);
+
+    case "compare-places":
+    case "maps_compare_places":
+      return searcher.comparePlaces(params);
+
     default:
       throw new Error(`Unknown tool: ${toolName}. Available: ${EXEC_TOOLS.join(", ")}`);
   }

src/config.ts

@@ -11,6 +11,9 @@ import { Elevation, ElevationParams } from "./tools/maps/elevation.js";
 import { SearchPlaces, SearchPlacesParams } from "./tools/maps/searchPlaces.js";
 import { Timezone, TimezoneParams } from "./tools/maps/timezone.js";
 import { Weather, WeatherParams } from "./tools/maps/weather.js";
+import { ExploreArea, ExploreAreaParams } from "./tools/maps/exploreArea.js";
+import { PlanRoute, PlanRouteParams } from "./tools/maps/planRoute.js";
+import { ComparePlaces, ComparePlacesParams } from "./tools/maps/comparePlaces.js";
 
 // All Google Maps tools are read-only API queries
 const MAPS_TOOL_ANNOTATIONS = {
@@ -101,6 +104,27 @@ const serverConfigs: ServerInstanceConfig[] = [
         annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: WeatherParams) => Weather.ACTION(params),
       },
+      {
+        name: ExploreArea.NAME,
+        description: ExploreArea.DESCRIPTION,
+        schema: ExploreArea.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
+        action: (params: ExploreAreaParams) => ExploreArea.ACTION(params),
+      },
+      {
+        name: PlanRoute.NAME,
+        description: PlanRoute.DESCRIPTION,
+        schema: PlanRoute.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
+        action: (params: PlanRouteParams) => PlanRoute.ACTION(params),
+      },
+      {
+        name: ComparePlaces.NAME,
+        description: ComparePlaces.DESCRIPTION,
+        schema: ComparePlaces.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
+        action: (params: ComparePlacesParams) => ComparePlaces.ACTION(params),
+      },
     ],
   },
 ];

src/services/PlacesSearcher.ts

@@ -316,6 +316,193 @@ export class PlacesSearcher {
     }
   }
 
+  // --------------- Composite Tools ---------------
+
+  async exploreArea(params: { location: string; types?: string[]; radius?: number; topN?: number }): Promise<any> {
+    const types = params.types || ["restaurant", "cafe", "attraction"];
+    const radius = params.radius || 1000;
+    const topN = params.topN || 3;
+
+    // 1. Geocode
+    const geo = await this.geocode(params.location);
+    if (!geo.success || !geo.data) throw new Error(geo.error || "Geocode failed");
+    const { lat, lng } = geo.data.location;
+
+    // 2. Search each type
+    const categories: any[] = [];
+    for (const type of types) {
+      const search = await this.searchNearby({
+        center: { value: `${lat},${lng}`, isCoordinates: true },
+        keyword: type,
+        radius,
+      });
+      if (!search.success || !search.data) continue;
+
+      // 3. Get details for top N
+      const topPlaces = search.data.slice(0, topN);
+      const detailed = [];
+      for (const place of topPlaces) {
+        if (!place.place_id) continue;
+        const details = await this.getPlaceDetails(place.place_id);
+        detailed.push({
+          name: place.name,
+          address: place.address,
+          rating: place.rating,
+          total_ratings: place.total_ratings,
+          open_now: place.open_now,
+          phone: details.data?.phone,
+          website: details.data?.website,
+        });
+      }
+      categories.push({ type, count: search.data.length, top: detailed });
+    }
+
+    return {
+      success: true,
+      data: {
+        location: { address: geo.data.formatted_address, lat, lng },
+        radius,
+        categories,
+      },
+    };
+  }
+
+  async planRoute(params: {
+    stops: string[];
+    mode?: "driving" | "walking" | "bicycling" | "transit";
+    optimize?: boolean;
+  }): Promise<any> {
+    const mode = params.mode || "driving";
+    const stops = params.stops;
+    if (stops.length < 2) throw new Error("Need at least 2 stops");
+
+    // 1. Geocode all stops
+    const geocoded: Array<{ originalName: string; address: string; lat: number; lng: number }> = [];
+    for (const stop of stops) {
+      const geo = await this.geocode(stop);
+      if (!geo.success || !geo.data) throw new Error(`Failed to geocode: ${stop}`);
+      geocoded.push({
+        originalName: stop,
+        address: geo.data.formatted_address,
+        lat: geo.data.location.lat,
+        lng: geo.data.location.lng,
+      });
+    }
+
+    // 2. If optimize requested and > 2 stops, use distance-matrix + nearest-neighbor
+    //    Use driving mode for optimization (transit matrix requires departure_time and often returns null)
+    let orderedStops = geocoded;
+    if (params.optimize !== false && geocoded.length > 2) {
+      const matrix = await this.calculateDistanceMatrix(stops, stops, "driving");
+      if (matrix.success && matrix.data) {
+        // Nearest-neighbor from first stop
+        const visited = new Set<number>([0]);
+        const order = [0];
+        let current = 0;
+        while (visited.size < geocoded.length) {
+          let bestIdx = -1;
+          let bestDuration = Infinity;
+          for (let i = 0; i < geocoded.length; i++) {
+            if (visited.has(i)) continue;
+            const dur = matrix.data.durations[current]?.[i]?.value ?? Infinity;
+            if (dur < bestDuration) {
+              bestDuration = dur;
+              bestIdx = i;
+            }
+          }
+          if (bestIdx === -1) break;
+          visited.add(bestIdx);
+          order.push(bestIdx);
+          current = bestIdx;
+        }
+        orderedStops = order.map((i) => geocoded[i]);
+      }
+    }
+
+    // 3. Get directions between consecutive stops (use original names for reliable results)
+    const legs: any[] = [];
+    let totalDistance = 0;
+    let totalDuration = 0;
+    for (let i = 0; i < orderedStops.length - 1; i++) {
+      const dir = await this.getDirections(orderedStops[i].originalName, orderedStops[i + 1].originalName, mode);
+      if (dir.success && dir.data) {
+        totalDistance += dir.data.total_distance.value;
+        totalDuration += dir.data.total_duration.value;
+        legs.push({
+          from: orderedStops[i].originalName,
+          to: orderedStops[i + 1].originalName,
+          distance: dir.data.total_distance.text,
+          duration: dir.data.total_duration.text,
+        });
+      } else {
+        legs.push({
+          from: orderedStops[i].originalName,
+          to: orderedStops[i + 1].originalName,
+          distance: "unknown",
+          duration: "unknown",
+          note: dir.error || "Directions unavailable for this segment",
+        });
+      }
+    }
+
+    return {
+      success: true,
+      data: {
+        mode,
+        optimized: params.optimize !== false && geocoded.length > 2,
+        stops: orderedStops.map((s) => `${s.originalName} (${s.address})`),
+        legs,
+        total_distance: `${(totalDistance / 1000).toFixed(1)} km`,
+        total_duration: `${Math.round(totalDuration / 60)} min`,
+      },
+    };
+  }
+
+  async comparePlaces(params: {
+    query: string;
+    userLocation?: { latitude: number; longitude: number };
+    limit?: number;
+  }): Promise<any> {
+    const limit = params.limit || 5;
+
+    // 1. Search
+    const search = await this.searchText({ query: params.query });
+    if (!search.success || !search.data) throw new Error(search.error || "Search failed");
+
+    const places = search.data.slice(0, limit);
+
+    // 2. Get details for each
+    const compared: any[] = [];
+    for (const place of places) {
+      const details = await this.getPlaceDetails(place.place_id);
+      compared.push({
+        name: place.name,
+        address: place.address,
+        rating: place.rating,
+        total_ratings: place.total_ratings,
+        open_now: place.open_now,
+        phone: details.data?.phone,
+        website: details.data?.website,
+        price_level: details.data?.price_level,
+      });
+    }
+
+    // 3. Distance from user location (if provided)
+    if (params.userLocation && compared.length > 0) {
+      const origin = `${params.userLocation.latitude},${params.userLocation.longitude}`;
+      const destinations = places.map((p: any) => `${p.location.lat},${p.location.lng}`);
+      const matrix = await this.calculateDistanceMatrix([origin], destinations, "driving");
+      if (matrix.success && matrix.data) {
+        for (let i = 0; i < compared.length; i++) {
+          compared[i].distance = matrix.data.distances[0]?.[i]?.text;
+          compared[i].drive_time = matrix.data.durations[0]?.[i]?.text;
+        }
+      }
+    }
+
+    return { success: true, data: compared };
+  }
+
   async getElevation(locations: Array<{ latitude: number; longitude: number }>): Promise<ElevationResponse> {
     try {
       const result = await this.mapsTools.getElevation(locations);

src/tools/maps/comparePlaces.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { PlacesSearcher } from "../../services/PlacesSearcher.js";
+import { getCurrentApiKey } from "../../utils/requestContext.js";
+
+const NAME = "maps_compare_places";
+const DESCRIPTION =
+  "Compare multiple places side-by-side in one call — searches by query, gets details for each result, and optionally calculates distance from your location. Use when the user asks 'which restaurant should I pick', 'compare these hotels', or needs a decision table. Replaces the manual chain of search-places → place-details → distance-matrix.";
+
+const SCHEMA = {
+  query: z.string().describe("Search query (e.g., 'ramen near Shibuya', 'hotels in Taipei')"),
+  userLocation: z
+    .object({
+      latitude: z.number().describe("Your latitude"),
+      longitude: z.number().describe("Your longitude"),
+    })
+    .optional()
+    .describe("Your current location — if provided, adds distance and drive time to each result"),
+  limit: z.number().optional().describe("Max places to compare (default: 5)"),
+};
+
+export type ComparePlacesParams = z.infer<z.ZodObject<typeof SCHEMA>>;
+
+async function ACTION(params: any): Promise<{ content: any[]; isError?: boolean }> {
+  try {
+    const apiKey = getCurrentApiKey();
+    const searcher = new PlacesSearcher(apiKey);
+    const result = await searcher.comparePlaces(params);
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+      isError: false,
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Error comparing places: ${error.message}` }],
+    };
+  }
+}
+
+export const ComparePlaces = { NAME, DESCRIPTION, SCHEMA, ACTION };

src/tools/maps/exploreArea.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { PlacesSearcher } from "../../services/PlacesSearcher.js";
+import { getCurrentApiKey } from "../../utils/requestContext.js";
+
+const NAME = "maps_explore_area";
+const DESCRIPTION =
+  "Explore what's around a location in one call — searches multiple place types, gets details for the top results, and returns a categorized summary. Use when the user asks 'what's around here', 'explore the area near my hotel', or needs a quick overview of a neighborhood. Replaces the manual chain of geocode → search-nearby → place-details.";
+
+const SCHEMA = {
+  location: z.string().describe("Address or landmark to explore around"),
+  types: z
+    .array(z.string())
+    .optional()
+    .describe("Place types to search (default: restaurant, cafe, attraction). Examples: hotel, bar, park, museum"),
+  radius: z.number().optional().describe("Search radius in meters (default: 1000)"),
+  topN: z.number().optional().describe("Number of top results per type to get details for (default: 3)"),
+};
+
+export type ExploreAreaParams = z.infer<z.ZodObject<typeof SCHEMA>>;
+
+async function ACTION(params: any): Promise<{ content: any[]; isError?: boolean }> {
+  try {
+    const apiKey = getCurrentApiKey();
+    const searcher = new PlacesSearcher(apiKey);
+    const result = await searcher.exploreArea(params);
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+      isError: false,
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Error exploring area: ${error.message}` }],
+    };
+  }
+}
+
+export const ExploreArea = { NAME, DESCRIPTION, SCHEMA, ACTION };

src/tools/maps/planRoute.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { PlacesSearcher } from "../../services/PlacesSearcher.js";
+import { getCurrentApiKey } from "../../utils/requestContext.js";
+
+const NAME = "maps_plan_route";
+const DESCRIPTION =
+  "Plan an optimized multi-stop route in one call — geocodes all stops, finds the most efficient visit order using distance-matrix, and returns step-by-step directions between each stop. Use when the user says 'visit these 5 places efficiently', 'plan a route through A, B, C', or needs a multi-stop itinerary. Replaces the manual chain of geocode → distance-matrix → directions.";
+
+const SCHEMA = {
+  stops: z.array(z.string()).min(2).describe("List of addresses or landmarks to visit (minimum 2)"),
+  mode: z.enum(["driving", "walking", "bicycling", "transit"]).optional().describe("Travel mode (default: driving)"),
+  optimize: z
+    .boolean()
+    .optional()
+    .describe("Auto-optimize visit order by nearest-neighbor (default: true). Set false to keep original order."),
+};
+
+export type PlanRouteParams = z.infer<z.ZodObject<typeof SCHEMA>>;
+
+async function ACTION(params: any): Promise<{ content: any[]; isError?: boolean }> {
+  try {
+    const apiKey = getCurrentApiKey();
+    const searcher = new PlacesSearcher(apiKey);
+    const result = await searcher.planRoute(params);
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+      isError: false,
+    };
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Error planning route: ${error.message}` }],
+    };
+  }
+}
+
+export const PlanRoute = { NAME, DESCRIPTION, SCHEMA, ACTION };