feat: implement avoid_highways and avoid_tolls on route planner (#80)

Add drive-only avoid_tolls and avoid_highways options to maps_directions, maps_distance_matrix, and maps_plan_route (service-level routeModifiers with non-driving guard). Also fix CLI exec output truncation for large responses (e.g. static maps) by replacing console.log+process.exit with process.stdout.write+process.exitCode.

Co-authored-by: André Herculano <228650+andresilveirah@users.noreply.github.com>

Author: andresilveirah

README.md

@@ -68,8 +68,8 @@ Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add sup
 | `maps_place_details` | Get full details for a place by its place_id — reviews, phone, website, hours. Optional `maxPhotos` param returns photo URLs. |
 | `maps_geocode` | Convert an address or landmark name into GPS coordinates. |
 | `maps_reverse_geocode` | Convert GPS coordinates into a street address. |
-| `maps_distance_matrix` | Calculate travel distances and times between multiple origins and destinations. |
-| `maps_directions` | Get step-by-step navigation between two points with route details. |
+| `maps_distance_matrix` | Calculate travel distances and times between multiple origins and destinations. Driving mode supports `avoid_tolls` and `avoid_highways`. |
+| `maps_directions` | Get step-by-step navigation between two points with route details. Driving mode supports `avoid_tolls` and `avoid_highways`. |
 | `maps_elevation` | Get elevation (meters above sea level) for geographic coordinates. |
 | `maps_timezone` | Get timezone ID, name, UTC/DST offsets, and local time for coordinates. |
 | `maps_weather` | Get current weather conditions or forecast — temperature, humidity, wind, UV, precipitation. |
@@ -79,7 +79,7 @@ Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add sup
 | `maps_search_along_route` | Search for places along a route between two points — ranked by minimal detour time. |
 | **Composite Tools** | |
 | `maps_explore_area` | Explore what's around a location — searches multiple place types and gets details in one call. |
-| `maps_plan_route` | Plan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering. |
+| `maps_plan_route` | Plan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering. Driving mode supports `avoid_tolls` and `avoid_highways`. |
 | `maps_compare_places` | Compare places side-by-side — searches, gets details, and optionally calculates distances. |
 | `maps_local_rank_tracker` | Track a business's local search ranking across a geographic grid — like LocalFalcon. Supports up to 3 keywords for batch scanning. Returns rank at each point, top-3 competitors, and metrics (ARP, ATRP, SoLV). |
 

skills/google-maps/SKILL.md

@@ -50,8 +50,8 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 ### Routing & Distance
 | Tool | When to use | Example |
 |------|-------------|---------|
-| `maps_directions` | How to get from A to B | "Route from Taipei Main Station to the airport" |
-| `maps_distance_matrix` | Compare distances across multiple points | "Which of these 3 hotels is closest to the airport?" |
+| `maps_directions` | How to get from A to B, including drive-only avoid-tolls/highways controls | "Route from Taipei Main Station to airport avoiding tolls" |
+| `maps_distance_matrix` | Compare distances across multiple points, including drive-only avoid-tolls/highways controls | "Which of these 3 hotels is closest to airport without highways?" |
 | `maps_search_along_route` | Find places along a route (meals, stops) ranked by detour time | "Restaurants between Fushimi Inari and Kiyomizu-dera" |
 
 ### Environment
@@ -71,7 +71,7 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 | Tool | When to use | Example |
 |------|-------------|---------|
 | `maps_explore_area` | Overview of a neighborhood | "What's around Tokyo Tower?" |
-| `maps_plan_route` | Multi-stop optimized itinerary (Routes API waypoint optimization, up to 25 stops) | "Visit these 5 places efficiently" |
+| `maps_plan_route` | Multi-stop optimized itinerary (Routes API waypoint optimization, up to 25 stops) with drive-only avoid-tolls/highways controls | "Visit these 5 places efficiently without tolls" |
 | `maps_compare_places` | Side-by-side comparison | "Which ramen shop near Shibuya?" |
 | `maps_local_rank_tracker` | Local SEO grid rank tracking | "How does this dentist rank across the area?" |
 

skills/google-maps/references/tools-api.md

@@ -168,6 +168,8 @@ exec maps_directions '{"origin": "Tokyo Tower", "destination": "Shibuya Station"
 | mode | string | no | Travel mode: driving, walking, bicycling, transit |
 | departure_time | string | no | Departure time (ISO 8601 or "now") |
 | arrival_time | string | no | Desired arrival time (transit only) |
+| avoid_tolls | boolean | no | Avoid toll roads where reasonable. Driving only |
+| avoid_highways | boolean | no | Avoid highways where reasonable. Driving only |
 
 ---
 
@@ -186,6 +188,9 @@ exec maps_distance_matrix '{"origins": ["Tokyo Tower"], "destinations": ["Shibuy
 | origins | string[] | yes | List of origin addresses |
 | destinations | string[] | yes | List of destination addresses |
 | mode | string | no | Travel mode: driving, walking, bicycling, transit |
+| departure_time | string | no | Departure time in ISO 8601 format for traffic-aware driving estimates |
+| avoid_tolls | boolean | no | Avoid toll roads where reasonable. Driving only |
+| avoid_highways | boolean | no | Avoid highways where reasonable. Driving only |
 
 ---
 
@@ -377,6 +382,9 @@ exec maps_plan_route '{"stops": ["Tokyo Tower", "Shibuya Station", "Shinjuku Sta
 | stops | string[] | yes | Addresses or landmarks (min 2, up to 27 total with origin + destination) |
 | mode | string | no | driving, walking, bicycling, transit (default: driving) |
 | optimize | boolean | no | Auto-optimize visit order via Routes API (default: true). Not available for transit mode. |
+| departure_time | string | no | Departure time in ISO 8601 format for traffic-aware driving routes |
+| avoid_tolls | boolean | no | Avoid toll roads where reasonable. Driving only |
+| avoid_highways | boolean | no | Avoid highways where reasonable. Driving only |
 
 ---
 

src/cli.ts

@@ -139,12 +139,21 @@ async function execTool(toolName: string, params: any, apiKey: string): Promise<
         params.destination,
         params.mode,
         params.departure_time,
-        params.arrival_time
+        params.arrival_time,
+        params.avoid_tolls,
+        params.avoid_highways
       );
 
     case "distance-matrix":
     case "maps_distance_matrix":
-      return searcher.calculateDistanceMatrix(params.origins, params.destinations, params.mode, params.departure_time);
+      return searcher.calculateDistanceMatrix(
+        params.origins,
+        params.destinations,
+        params.mode,
+        params.departure_time,
+        params.avoid_tolls,
+        params.avoid_highways
+      );
 
     case "elevation":
     case "maps_elevation":
@@ -274,25 +283,25 @@ if (isRunDirectly || isMainModule) {
       },
       async (argv) => {
         if (!argv.apikey) {
-          console.error(
+          process.stderr.write(
             JSON.stringify(
               {
                 error: "GOOGLE_MAPS_API_KEY not set. Use --apikey or set GOOGLE_MAPS_API_KEY environment variable.",
               },
               null,
               2
-            )
+            ) + "\n"
           );
-          process.exit(1);
+          process.exitCode = 1;
+          return;
         }
         try {
           const params = argv.params ? JSON.parse(argv.params as string) : {};
           const result = await execTool(argv.tool as string, params, argv.apikey as string);
-          console.log(JSON.stringify(result, null, 2));
-          process.exit(0);
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
         } catch (error: any) {
-          console.error(JSON.stringify({ error: error.message }, null, 2));
-          process.exit(1);
+          process.stderr.write(JSON.stringify({ error: error.message }, null, 2) + "\n");
+          process.exitCode = 1;
         }
       }
     )

src/services/PlacesSearcher.ts

@@ -298,14 +298,18 @@ export class PlacesSearcher {
     origins: string[],
     destinations: string[],
     mode: "driving" | "walking" | "bicycling" | "transit" = "driving",
-    departure_time?: string
+    departure_time?: string,
+    avoid_tolls?: boolean,
+    avoid_highways?: boolean
   ): Promise<DistanceMatrixResponse> {
     try {
       const result = await this.routesService.computeRouteMatrix({
         origins,
         destinations,
         mode,
         ...(departure_time ? { departureTime: new Date(departure_time) } : {}),
+        ...(avoid_tolls !== undefined ? { avoidTolls: avoid_tolls } : {}),
+        ...(avoid_highways !== undefined ? { avoidHighways: avoid_highways } : {}),
       });
 
       return {
@@ -325,7 +329,9 @@ export class PlacesSearcher {
     destination: string,
     mode: "driving" | "walking" | "bicycling" | "transit" = "driving",
     departure_time?: string,
-    arrival_time?: string
+    arrival_time?: string,
+    avoid_tolls?: boolean,
+    avoid_highways?: boolean
   ): Promise<DirectionsResponse> {
     try {
       const departureTime = departure_time ? new Date(departure_time) : undefined;
@@ -336,6 +342,8 @@ export class PlacesSearcher {
         mode,
         ...(departureTime ? { departureTime } : {}),
         ...(arrivalTime ? { arrivalTime } : {}),
+        ...(avoid_tolls !== undefined ? { avoidTolls: avoid_tolls } : {}),
+        ...(avoid_highways !== undefined ? { avoidHighways: avoid_highways } : {}),
       });
 
       return {
@@ -495,6 +503,8 @@ export class PlacesSearcher {
     mode?: "driving" | "walking" | "bicycling" | "transit";
     optimize?: boolean;
     departure_time?: string;
+    avoid_tolls?: boolean;
+    avoid_highways?: boolean;
   }): Promise<any> {
     const mode = params.mode || "driving";
     const stops = params.stops;
@@ -527,6 +537,8 @@ export class PlacesSearcher {
       intermediates,
       optimizeWaypointOrder: shouldOptimize,
       ...(params.departure_time ? { departureTime: new Date(params.departure_time) } : {}),
+      ...(params.avoid_tolls !== undefined ? { avoidTolls: params.avoid_tolls } : {}),
+      ...(params.avoid_highways !== undefined ? { avoidHighways: params.avoid_highways } : {}),
     });
 
     const route = routeResult.routes[0];

src/services/RoutesService.ts

@@ -84,6 +84,27 @@ function toWaypoint(location: string): any {
   return { address: location };
 }
 
+function buildRouteModifiers(params: { avoidTolls?: boolean; avoidHighways?: boolean }, travelMode: string): any {
+  const routeModifiers: Record<string, boolean> = {};
+
+  if (params.avoidTolls) {
+    routeModifiers.avoidTolls = true;
+  }
+  if (params.avoidHighways) {
+    routeModifiers.avoidHighways = true;
+  }
+
+  if (Object.keys(routeModifiers).length === 0) {
+    return undefined;
+  }
+
+  if (travelMode !== "DRIVE") {
+    throw new Error('Route modifiers "avoid_tolls" and "avoid_highways" are only supported with mode "driving".');
+  }
+
+  return routeModifiers;
+}
+
 /**
  * Routes API REST client.
  *
@@ -112,6 +133,8 @@ export class RoutesService {
     arrivalTime?: Date;
     intermediates?: string[];
     optimizeWaypointOrder?: boolean;
+    avoidTolls?: boolean;
+    avoidHighways?: boolean;
   }): Promise<{
     routes: any[];
     summary: string;
@@ -135,6 +158,11 @@ export class RoutesService {
       requestBody.routingPreference = "TRAFFIC_AWARE";
     }
 
+    const routeModifiers = buildRouteModifiers(params, travelMode);
+    if (routeModifiers) {
+      requestBody.routeModifiers = routeModifiers;
+    }
+
     // Departure/arrival time (only set if explicitly provided — Routes API rejects past timestamps)
     if (params.arrivalTime) {
       requestBody.arrivalTime = params.arrivalTime.toISOString();
@@ -219,6 +247,8 @@ export class RoutesService {
     destinations: string[];
     mode?: string;
     departureTime?: Date;
+    avoidTolls?: boolean;
+    avoidHighways?: boolean;
   }): Promise<{
     distances: any[][];
     durations: any[][];
@@ -239,6 +269,11 @@ export class RoutesService {
       requestBody.routingPreference = "TRAFFIC_AWARE";
     }
 
+    const routeModifiers = buildRouteModifiers(params, travelMode);
+    if (routeModifiers) {
+      requestBody.routeModifiers = routeModifiers;
+    }
+
     if (params.departureTime) {
       requestBody.departureTime = params.departureTime.toISOString();
     }

src/tools/maps/directions.ts

@@ -15,6 +15,11 @@ const SCHEMA = {
     .describe("Travel mode for directions"),
   departure_time: z.string().optional().describe("Departure time (ISO string format)"),
   arrival_time: z.string().optional().describe("Arrival time (ISO string format)"),
+  avoid_tolls: z.boolean().optional().describe('Avoid toll roads where reasonable. Only supported with mode "driving".'),
+  avoid_highways: z
+    .boolean()
+    .optional()
+    .describe('Avoid highways where reasonable. Only supported with mode "driving".'),
 };
 
 export type DirectionsParams = z.infer<z.ZodObject<typeof SCHEMA>>;
@@ -29,7 +34,9 @@ async function ACTION(params: any): Promise<{ content: any[]; isError?: boolean
       params.destination,
       params.mode,
       params.departure_time,
-      params.arrival_time
+      params.arrival_time,
+      params.avoid_tolls,
+      params.avoid_highways
     );
 
     if (!result.success) {

src/tools/maps/distanceMatrix.ts

@@ -19,6 +19,11 @@ const SCHEMA = {
     .describe(
       "Departure time in ISO 8601 format (e.g. 2026-03-21T09:00:00Z). Enables traffic-aware duration estimates."
     ),
+  avoid_tolls: z.boolean().optional().describe('Avoid toll roads where reasonable. Only supported with mode "driving".'),
+  avoid_highways: z
+    .boolean()
+    .optional()
+    .describe('Avoid highways where reasonable. Only supported with mode "driving".'),
 };
 
 export type DistanceMatrixParams = z.infer<z.ZodObject<typeof SCHEMA>>;
@@ -32,7 +37,9 @@ async function ACTION(params: any): Promise<{ content: any[]; isError?: boolean
       params.origins,
       params.destinations,
       params.mode,
-      params.departure_time
+      params.departure_time,
+      params.avoid_tolls,
+      params.avoid_highways
     );
 
     if (!result.success) {

src/tools/maps/planRoute.ts

@@ -19,6 +19,11 @@ const SCHEMA = {
     .string()
     .optional()
     .describe("Departure time in ISO 8601 format (e.g. 2026-03-21T09:00:00Z). Enables traffic-aware routing."),
+  avoid_tolls: z.boolean().optional().describe('Avoid toll roads where reasonable. Only supported with mode "driving".'),
+  avoid_highways: z
+    .boolean()
+    .optional()
+    .describe('Avoid highways where reasonable. Only supported with mode "driving".'),
 };
 
 export type PlanRouteParams = z.infer<z.ZodObject<typeof SCHEMA>>;

tests/smoke.test.ts

@@ -243,17 +243,36 @@ async function testListTools(session: McpSession): Promise<void> {
     }
   }
 
-  // Verify departure_time parameter exists in plan_route and distance_matrix
+  // Verify routing parameters exist in route tools
   const planRoute = tools.find((t: any) => t.name === "maps_plan_route");
   assert(
     planRoute?.inputSchema?.properties?.departure_time !== undefined,
     "maps_plan_route has departure_time parameter"
   );
+  assert(planRoute?.inputSchema?.properties?.avoid_tolls !== undefined, "maps_plan_route has avoid_tolls parameter");
+  assert(
+    planRoute?.inputSchema?.properties?.avoid_highways !== undefined,
+    "maps_plan_route has avoid_highways parameter"
+  );
+  const directions = tools.find((t: any) => t.name === "maps_directions");
+  assert(directions?.inputSchema?.properties?.avoid_tolls !== undefined, "maps_directions has avoid_tolls parameter");
+  assert(
+    directions?.inputSchema?.properties?.avoid_highways !== undefined,
+    "maps_directions has avoid_highways parameter"
+  );
   const distMatrix = tools.find((t: any) => t.name === "maps_distance_matrix");
   assert(
     distMatrix?.inputSchema?.properties?.departure_time !== undefined,
     "maps_distance_matrix has departure_time parameter"
   );
+  assert(
+    distMatrix?.inputSchema?.properties?.avoid_tolls !== undefined,
+    "maps_distance_matrix has avoid_tolls parameter"
+  );
+  assert(
+    distMatrix?.inputSchema?.properties?.avoid_highways !== undefined,
+    "maps_distance_matrix has avoid_highways parameter"
+  );
 }
 
 async function testGeocode(session: McpSession): Promise<void> {
@@ -850,6 +869,7 @@ async function testExecMode(): Promise<void> {
       return execFileSync("node", [cliPath, "exec", tool, params, "--apikey", API_KEY], {
         encoding: "utf-8",
         timeout: 30000,
+        maxBuffer: 10 * 1024 * 1024,
       }).trim();
     } catch (err: any) {
       return err.stdout?.trim() ?? err.message;
@@ -1059,6 +1079,28 @@ async function testTransitErrorMessages(session: McpSession): Promise<void> {
       }
     }
   }
+
+  const avoidResult = await sendRequest(session, "tools/call", {
+    name: "maps_directions",
+    arguments: {
+      origin: "Tokyo Station",
+      destination: "Nagoya Station",
+      mode: "walking",
+      avoid_highways: true,
+    },
+  });
+  const avoidContent = avoidResult?.result?.content ?? [];
+  assert(avoidContent.length > 0, "Invalid route modifiers returns content");
+  if (avoidContent.length > 0) {
+    const text = avoidContent[0]?.text ?? "";
+    const isError = avoidResult?.result?.isError === true;
+    assert(isError, "Non-driving route modifiers return isError=true");
+    assert(
+      text.includes('only supported with mode "driving"'),
+      "Non-driving route modifiers return clear error",
+      `got: ${text.slice(0, 200)}`
+    );
+  }
 }
 
 // --------------- Main ---------------