distance-matrix-calculator

name	distance-matrix-calculator
description	Calculates distances and travel times between multiple locations for route planning or optimization. Computes a complete distance matrix, supports different travel modes, and returns both distance and time estimates.

Instructions

Primary Objective

When the user requests route planning, optimization, or distance calculations between multiple points, use this skill to compute the most efficient path. The core task is to generate a complete distance and time matrix between all specified locations and then determine the optimal visiting order (solving a Traveling Salesman Problem - TSP) when a starting point is defined.

Core Workflow

1. Parse the Request & Gather Locations

• Identify Attractions/Destinations: Extract all locations the user wants to visit from their request and any referenced documents (e.g., recommendation.md). List each attraction separately, even if they are close.
• Identify the Starting Point: Determine the user's current location or specified starting point (e.g., "I am currently at X").
• Geocode All Points: Use google_map-maps_geocode or google_map-maps_search_places to obtain precise latitude/longitude coordinates and formatted addresses for every location (starting point + all destinations).

2. Generate the Distance Matrix

• Use google_map-maps_distance_matrix with all gathered coordinates as both origins and destinations.
• Set the mode parameter based on the request (e.g., "walking", "driving"). Default to "walking" if unspecified.
• Output Analysis: The tool returns a matrix. Extract the distance.value (meters) and duration.value (seconds) for every origin-destination pair. Organize this data into clear numerical arrays for calculation.

3. Calculate the Optimal Route (TSP)

• Goal: Find the shortest total travel path that starts at the given starting point and visits all destination points exactly once.
• Method: For a small number of points (n ≤ 6), perform a brute-force search over all possible permutations of destinations.
• Process:
  1. Fix the starting point as the first location in the sequence.
  2. Generate all possible orders (permutations) for the remaining destination points.
  3. For each permutation, sum the distances between consecutive points using the pre-computed matrix.
  4. Identify the permutation with the minimum total distance.
• Validation: Manually check a few of the top-performing routes to ensure the result is logical (e.g., doesn't criss-cross unnecessarily).

4. Generate Detailed Directions

• For each leg of the chosen optimal route, use google_map-maps_directions to get turn-by-turn navigation instructions.
• Extract and format the summary, distance.text, duration.text, and key steps from steps[n].instructions.

5. Format and Save the Output

• Structure the final plan according to any user-specified format (e.g., a provided format.json template).
• The output must include:
  • road_plan: An array for each leg with from, to, distance, estimated_time, and directions.
  • total_distance: The sum of all leg distances.
  • total_time: The sum of all leg durations.
• Save the final JSON file using filesystem-write_file.
• Verify the written file using filesystem-read_file.

Key Triggers & User Phrases

• "Plan the shortest walking/driving route"
• "Optimize the visiting order"
• "Calculate distances between these places"
• "Give me a tour of all these attractions"
• "Find the most efficient path"

Error Handling & Assumptions

• Missing Coordinates: If a place cannot be found, use a broader search query or ask the user for clarification.
• Matrix Errors: If the distance matrix call fails for some pairs, you may need to call the directions API for those specific pairs as a fallback.
• Time vs. Distance Optimization: By default, optimize for shortest total distance. If the user specifies "fastest route," optimize for shortest total time.
• Single Destination: If only one destination is provided, simply return the direct route from start to finish.