MCP Tools Reference: mapstools.googleapis.com

Ferramenta: search_places

Chame essa ferramenta quando a solicitação do usuário for encontrar lugares, empresas, endereços, locais, pontos de interesse ou qualquer outra pesquisa relacionada ao Google Maps.

Requisitos de entrada (CRÍTICOS):

1. text_query (string - OBRIGATÓRIO): a consulta de pesquisa principal. Isso precisa definir claramente o que o usuário está procurando.

   • Exemplos: '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'.
   • Para detalhes específicos do lugar: inclua o atributo solicitado (por exemplo, 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

2. location_bias (objeto - OPCIONAL): use para priorizar resultados próximos a uma área geográfica específica.

   • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • Uso:
     • Para definir um raio de 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • Para priorizar o ponto central: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omitindo radius_meters).

3. language_code (string - OPCIONAL): o idioma em que o resumo dos resultados da pesquisa será mostrado.

   • Formato: um código de idioma de duas letras (ISO 639-1), seguido opcionalmente por um sublinhado e um código de país de duas letras (ISO 3166-1 alfa-2), por exemplo, en, ja, en_US, zh_CN, es_MX. Se o código de idioma não for fornecido, os resultados serão em inglês.

4. region_code (string - OPCIONAL): o código de região CLDR Unicode do usuário. Esse parâmetro é usado para mostrar os Place Details, como o nome específico da região, se disponível. O parâmetro pode afetar os resultados com base na legislação aplicável.

   • Formato: um código de país com duas letras (ISO 3166-1 alfa-2), por exemplo, US, CA.

5. page_size (número inteiro - OPCIONAL): o número máximo de lugares a serem retornados, de 1 a 10. O padrão é 5. Defina acima de 5 somente quando o usuário quiser comparar mais de 5 lugares. Valores de 6 a 10 têm custo e latência mais altos.

6. include_extended_details (booleano - OPCIONAL): defina esse campo como true quando a solicitação do usuário exigir insights qualitativos detalhados, dinâmicas em tempo real ou atributos de entidade especializados. O padrão é false. Definir como true gera custos e latência mais altos.

Instruções para chamada de ferramenta:

• Informações de localização (CRÍTICO): a pesquisa precisa conter informações de localização suficientes. Se o local for ambíguo (por exemplo, apenas "pizzarias"), é obrigatório especificá-lo no text_query (por exemplo, "pizzarias em Nova York") ou usar o parâmetro location_bias. Inclua o nome da cidade, do estado/província e da região/país, se necessário, para evitar ambiguidade.

• Sempre forneça o text_query mais específico e rico em contexto possível.

• Use location_bias somente se as coordenadas forem fornecidas explicitamente ou se for apropriado e necessário inferir um local com base no contexto conhecido de um usuário para ter resultados melhores.

• A saída embasada precisa ser atribuída à fonte usando as informações do campo attribution, quando disponíveis.

O exemplo de código a seguir mostra como usar curl para chamar a ferramenta MCP search_places.

Esquema de entrada

{
  "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
}

Esquema de saída

{
  "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
}

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando uma solicitação de confirmação pode ser enviada a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

• readOnlyHint: se for verdadeiro, a ferramenta não vai modificar o ambiente. (Padrão: falso).
• destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
• idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. (Padrão: falso).
• openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ❌ | Dica somente leitura: ✅ | Dica de jogos de mundo aberto: ❌