MCP Reference: mapstools.googleapis.com

Call this tool when the user's request is to find places, businesses, addresses, locations, points of interest, or any other Google Maps related search.

Input Requirements (CRITICAL):

1. text_query (string - MANDATORY): The primary search query. This must clearly define what the user is looking for.

   • Examples: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
   • For specific place details: Include the requested attribute (e.g., 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

2. location_bias (object - OPTIONAL): Use this to prioritize results near a specific geographic area.

   • Format: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • Usage:
     • To bias to a 5km radius: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • To bias strongly to the center point: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omitting radius_meters).

3. language_code (string - OPTIONAL): The language to show the search results summary in.

   • Format: A two-letter language code (ISO 639-1), optionally followed by an underscore and a two-letter country code (ISO 3166-1 alpha-2), e.g., en, ja, en_US, zh_CN, es_MX. If the language code is not provided, the results will be in English.

4. region_code (string - OPTIONAL): The Unicode CLDR region code of the user. This parameter is used to display the place details, like region-specific place name, if available. The parameter canaffect results based on applicable law.

   • Format: A two-letter country code (ISO 3166-1 alpha-2), e.g., US, CA.

5. page_size (integer - OPTIONAL): The maximum number of places to return, from 1 to 10. Defaults to 5. Set above 5 only when the user wants to compare more than 5 places; values from 6 to 10 incur higher cost and higher latency.

6. include_extended_details (boolean - OPTIONAL): Set this field to true when the user request requires rich qualitativeinsights, real-time dynamics, or specialized entity attributes. Defaults to false. Setting this to true incurs higher cost and latency.

Instructions for Tool Call:

• Location Information (CRITICAL): The search must contain sufficient location information. If the location is ambiguous (e.g., just "pizza places"), you must specify it in the text_query (e.g., "pizza places in New York") or use the location_bias parameter. Include city, state/province, and region/country name if needed for disambiguation.

• Always provide the most specific and contextually rich text_query possible.

• Only use location_bias if coordinates are explicitly provided or if inferring a location from a user's known context is appropriate and necessary for better results.

• The grounded output must be attributed to the source using the information from the attribution field when available.

Computes travel routes between an origin and a destination, optionally through intermediate stops. Returns the distance and duration for each route.

Input Requirements (CRITICAL):

1. origin and destination (objects - MANDATORY): Each must be provided using exactly one of:

   • address (string, e.g., 'Eiffel Tower, Paris'). Named places, landmarks, and businesses are resolved directly, so do NOT call search_places first just to geocode a waypoint. Include any city, region, or country the user mentioned.
   • lat_lng (object, {"latitude": number, "longitude": number}).
   • place_id (string, e.g., 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), for example from search_places.

2. intermediate_waypoints (array of objects - OPTIONAL): Up to 25 stops to pass through, in order, between the origin and destination. Same format as origin. Not supported with TRANSIT. Only include stops the user asked for; specifying more than 10 intermediate waypoints will incur a higher cost and higher latency.

3. travel_mode (enum - OPTIONAL): DRIVE (default), WALK, BICYCLE, or TRANSIT.

4. Timing (OPTIONAL - set at most ONE): RFC 3339 timestamps with a UTC offset, e.g., '2026-09-19T08:00:00-07:00'. Defaults to departing now. For TRANSIT, the time can be up to 7 days in the past or up to 100 days in the future. For other modes, the time can be up to 365 days in the future and must not be in the past.

   • departure_time: Use when the user says when they will leave (e.g., "tomorrow at 8am").
   • arrival_time: Use when the user says when they must arrive (e.g., "be there by 9am").

5. routing_preference (enum - OPTIONAL):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (default): ignores live traffic, incidents, and closures. Lowest latency.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: uses live traffic conditions when available. Not supported for WALK or BICYCLE. Set this ONLY when the user asks about traffic, congestion, or a traffic-adjusted ETA. It incurs higher cost and latency.

6. location_bias (object - OPTIONAL): {"latitude": number, "longitude": number} used to disambiguate place names in waypoint addresses. If a name is ambiguous (e.g., "Springfield") and the user gave no region, keep the name as given in address and set location_bias toward the intended area instead of guessing a region.

7. compute_alternative_routes (boolean - OPTIONAL): Set to true only when the user asks for route options or alternatives. Defaults to false, which returns only the recommended route.

8. include_polyline (boolean - OPTIONAL): Set to true only when the route geometry (encoded_polyline) is needed. Defaults to false.

Instructions for Tool Call:

• If the origin or the destination is missing, you MUST ask the user for clarification before calling the tool.
• For "How far is A from B?" questions, use B as the origin and A as the destination.

Example Tool Call: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

Instructions for Response:

• When alternative routes are requested, routes are ordered from most to least recommended.
• If routes is empty, tell the user no route was found. Do not guess a route.
• To find places along a DRIVE route, pass the route's retrieval_token to search_along_route. The token is valid for 10 minutes.
• Only state facts returned by the tool. Do NOT invent turn-by-turn directions, transit lines, stations, platforms, or transfers.
• The grounded output must be attributed to the source using each route's attribution field when available.

Call this tool when the user wants to find places, businesses, or points of interest along a travel route (e.g., "gas stations on my way to Tahoe", "coffee shops between SF and San Jose"). Calling this tool incurs higher cost than search_places, so use search_places instead when searching near a single location rather than along a route.

Input Requirements (CRITICAL):

1. text_query (string - MANDATORY): A natural language description of what to search for along the route.

   • Examples: 'ev chargers', 'coffee', 'vegetarian restaurants', 'rest stops'.

2. Route specification (MANDATORY - provide exactly ONE of the following):

   • retrieval_token (string): The retrieval_token returned by a prior compute_routes call for a DRIVE route. Prefer this whenever the route was already computed. The token is valid for 10 minutes.
   • route_endpoints (object): The route's origin and destination. Each must be provided using one of address, lat_lng, or place_id.
     • Example: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
   • encoded_polyline (string): An encoded polyline representing a DRIVE route.

3. travel_mode (enum - OPTIONAL): DRIVE (default), WALK, or BICYCLE. WALK and BICYCLE are only supported with route_endpoints. TRANSIT is not supported.

4. routing_preference (enum - OPTIONAL):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (default): computes the route and detours without live traffic. Lowest latency.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: uses live traffic conditions when available. Not supported for WALK or BICYCLE. Set this ONLY when the user asks about traffic, congestion, or traffic-adjusted detour times. It incurs higher latency.

5. include_extended_details (boolean - OPTIONAL): Set to true only when the request requires qualitative review insights, specific menu items or offerings, atmosphere, visitor tips or busyness, EV charger availability, gas prices, or other rich qualitative details. Defaults to false. Enabling it may increase latency.

6. language_code (string - OPTIONAL): The language for the results summary and place details, e.g., en, ja, en-US. Defaults to en-US.

7. region_code (string - OPTIONAL): The Unicode CLDR region code of the user, e.g., US, CA.

Instructions for Tool Call:

• Each result includes a detour_summary (when available) describing the extra distance (localized_detour_distance) and, unless the route was given as encoded_polyline, the extra time (detour_duration) incurred by stopping at that place. Use it to compare options.
• The response summary may contain zero-based citations (e.g., "[0]") referencing entries in results.
• The grounded output must be attributed to the source using the attribution field of each results[].place when available.

Resolves a batch list of specific location queries (landmark names or exact addresses) into canonical Google Maps Place IDs.

Input Requirements (CRITICAL):

1. queries (array of objects - MANDATORY): A list of location queries to resolve. You may specify up to 20 queries.

   • Each query object must have:
     • text (string - MANDATORY): The text query representing a specific place name or address to resolve.
       • Examples: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

2. location_bias (object - OPTIONAL): Use this to prioritize results near a specific geographic area.

   • Format: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

3. region_code (string - OPTIONAL): The Unicode CLDR region code (two-letter country code, e.g., US, CA) of the user to bias the results.

Instructions for Tool Call:

• Specificity (CRITICAL): Queries must represent a specific place name or address. General searches like 'restaurants' or chain names like 'Starbucks' are not supported.
• Do NOT call this tool if the downstream tools you plan to invoke already accept raw address or place name strings directly.

Save to Google Maps:

• The response includes a save_to_maps_url field: a single Google Maps link containing all successfully resolved places.
• When the user wants to save, share, or open the resolved places as a list in Google Maps, present this link to the user. Do NOT construct this link yourself.

Error Handling (CRITICAL):

• This is a batch processing tool. A request might return "mixed results" (e.g. some queries resolve successfully while others fail).
• The output list of results is guaranteed to map 1:1 with the input queries indices. A failed query will result in an empty Result message (no entity is set) at its corresponding index in the results list.
• You MUST check the failed_requests map field in the response to identify which specific query index failed. The key of failed_requests represents the 0-based index of the failed query in the request. Do not assume the entire batch call failed because of a partial failure.

Resolves a list of Google Maps URLs into canonical Google Maps Place IDs.

When to call this tool (CRITICAL):

• Use this tool when the user provides one or more Google Maps sharing links or URLs (e.g. 'https://maps.app.goo.gl/...', 'https://www.google.com/maps/place/...', or 'https://maps.google.com/...') and you need to extract the underlying canonical Place IDs.
• You can specify up to 20 URLs to resolve in a single batch request.

Input Requirements (CRITICAL):

• urls (array of strings - MANDATORY): The list of Google Maps URLs to resolve. Each URL must be a valid, single-place Google Maps URL.

Save to Google Maps:

• The response includes a save_to_maps_url field: a single Google Maps link containing all successfully resolved places.
• When the user wants to save, share, or open the resolved places as a list in Google Maps (e.g. collecting places shared in a conversation), present this link to the user. Do NOT construct this link yourself.

Error Handling (CRITICAL):

• This is a batch processing tool. A request might return "mixed results" (e.g. some URLs resolve successfully while others fail).
• The output list of entities is guaranteed to map 1:1 with the input urls indices. A failed URL resolution will result in an empty Entity message (no fields are set) at its corresponding index in the entities list.
• You MUST check the failed_requests map field in the response to identify which specific URL index failed. The key of failed_requests represents the 0-based index of the failed URL in the request. Do not assume the entire batch call failed because of a partial failure.