MCP Tools Reference: mapstools.googleapis.com

Инструмент: search_places

Вызывайте этот инструмент, когда пользователь просит найти места, компании, адреса, местоположения, достопримечательности или выполнить любой другой поиск, связанный с Google Картами.

Требования к входным данным (КРИТИЧЕСКИ ВАЖНО):

1. text_query (строка, ОБЯЗАТЕЛЬНО). Основной поисковый запрос. В нем должно быть четко указано, что ищет пользователь.

   • Примеры: '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'.
   • Чтобы получить информацию о местах, укажите нужный атрибут, например 'Google Store Mountain View opening hours', 'SF MoMa phone number' или 'Shoreline Park Mountain View address'.

2. location_bias (объект, НЕОБЯЗАТЕЛЬНО). Используйте этот параметр, чтобы в первую очередь выводить результаты в пределах определенного географического региона.

   • Формат: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • Использование:
     • Чтобы задать смещение в радиусе 5 км: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • Чтобы задать сильное смещение к центральной точке, укажите {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (без radius_meters).

3. language_code (строка, необязательный параметр). Язык, на котором будет показана сводка результатов поиска.

   • Формат. Двухбуквенный код языка (ISO 639-1), за которым может следовать символ подчеркивания и двухбуквенный код страны (ISO 3166-1 alpha-2), например en, ja, en_US, zh_CN, es_MX. Если код языка не указан, результаты будут на английском.

4. region_code (строка, необязательный). Код региона пользователя в формате Unicode CLDR. Этот параметр используется для отображения информации о местах, например названия места для определенного региона, если оно доступно. Этот параметр может влиять на результаты в соответствии с действующим законодательством.

   • Формат. Двухбуквенный код страны (ISO 3166-1 alpha-2), например US, CA.

5. page_size (целое число, необязательно). Максимальное количество мест, которое нужно вернуть (от 1 до 10). Значение по умолчанию – 5. Устанавливайте значение выше 5, только если пользователю нужно сравнить более пяти мест. Значения от 6 до 10 приводят к увеличению стоимости и задержки.

6. include_extended_details (логическое значение, НЕОБЯЗАТЕЛЬНО). Задайте для этого поля значение true, если запрос пользователя требует подробных качественных данных, динамики в реальном времени или специализированных атрибутов объектов. Значение по умолчанию – false. Если задать значение true, стоимость и задержка будут выше.

Инструкции по вызову инструмента

• Геоданные (КРИТИЧЕСКИ ВАЖНО). Поисковый запрос должен содержать достаточно геоданных. Если местоположение неоднозначно (например, просто "пиццерии"), необходимо указать его в text_query (например, "пиццерии в Нью-Йорке") или использовать параметр location_bias. При необходимости укажите город, штат/провинцию и регион/страну.

• Всегда указывайте максимально точные и подробные text_query.

• Используйте location_bias, только если координаты указаны явно или если определение местоположения по известному контексту пользователя уместно и необходимо для получения лучших результатов.

• Обоснованный ответ должен быть связан с источником с помощью информации из поля attribution, если она доступна.

В примере кода ниже показано, как использовать curl для вызова инструмента MCP search_places.

Схема ввода

{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "includeExtendedDetails": boolean,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}

{
  "circle": {
    object (Circle)
  }
}

{
  "center": {
    object (LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}

{
  "latitude": number,
  "longitude": number
}

Схема вывода

{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "contentToken": string
}

{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}

{
  "latitude": number,
  "longitude": number
}

{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}

{
  "title": string,
  "url": string
}

Аннотации инструментов

Аннотации инструментов отправляются клиентам MCP, чтобы описать базовый риск, связанный с определенным инструментом. Большинство клиентов считают эти подсказки ненадежными, но их можно использовать, чтобы решить, когда пользователю может быть отправлен запрос на подтверждение.

Помимо строки заголовка, определены следующие логические подсказки:

• readOnlyHint: если задано значение true, инструмент не изменяет свою среду. Значение по умолчанию – false.
• destructiveHint: если задано значение True, инструмент может выполнять деструктивные действия. Если false, то инструмент может выполнять только действия по добавлению. Значение по умолчанию: true.
• idempotentHint – если задано значение True, повторный вызов инструмента с теми же аргументами не будет иметь дополнительного эффекта в его среде. Значение по умолчанию – false.
• openWorldHint: если задано значение true, инструмент может взаимодействовать с "открытым миром" внешних объектов. Если false, то инструмент может взаимодействовать только с внутренними объектами. Например, инструмент веб-поиска будет открытым миром, а инструмент памяти – нет.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌