MCP Reference: mapstools.googleapis.com

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.

Calcula trajetos entre uma origem e um destino, com a opção de incluir paradas intermediárias. Retorna a distância e a duração de cada trajeto.

Requisitos de entrada (CRÍTICOS):

1. origin e destination (objetos - OBRIGATÓRIO): cada um precisa ser fornecido usando exatamente um dos seguintes:

   • address (string, por exemplo, 'Eiffel Tower, Paris'). Lugares, pontos de referência e empresas com nome são resolvidos diretamente. Portanto, NÃO chame search_places primeiro apenas para geocodificar um waypoint. Inclua qualquer cidade, região ou país mencionado pelo usuário.
   • lat_lng (objeto, {"latitude": number, "longitude": number}).
   • place_id (string, por exemplo, 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), por exemplo, de search_places.

2. intermediate_waypoints (matriz de objetos, OPCIONAL): até 25 paradas para passar, em ordem, entre a origem e o destino. Mesmo formato de origin. Não é compatível com TRANSIT. Inclua apenas as paradas solicitadas pelo usuário. Especificar mais de 10 waypoints intermediários vai resultar em um custo mais alto e maior latência.

3. travel_mode (tipo enumerado - OPCIONAL): DRIVE (padrão), WALK, BICYCLE ou TRANSIT.

4. Horário (OPCIONAL - defina no máximo UM): carimbos de data/hora RFC 3339 com um ajuste de UTC, por exemplo, '2026-09-19T08:00:00-07:00'. O padrão é "partindo agora". Para TRANSIT, o horário pode ser de até 7 dias no passado ou até 100 dias no futuro. Para outros modos, o horário pode ser de até 365 dias no futuro e não pode ser no passado.

   • departure_time: use quando o usuário disser quando vai sair (por exemplo, "amanhã às 8h").
   • arrival_time: use quando o usuário disser o horário em que precisa chegar (por exemplo, "chegar às 9h").

5. routing_preference (tipo enumerado - OPCIONAL):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (padrão): ignora o trânsito em tempo real, os incidentes e as interdições. Latência mais baixa.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: usa as condições de trânsito em tempo real quando disponíveis. Não há suporte para WALK ou BICYCLE. Defina isso APENAS quando o usuário perguntar sobre o trânsito, congestionamento ou um HEC ajustado ao trânsito. Ela gera custos e latência mais altos.

6. location_bias (objeto, OPCIONAL): {"latitude": number, "longitude": number} usado para eliminar a ambiguidade de nomes de lugares em endereços de waypoints. Se um nome for ambíguo (por exemplo, "Springfield") e o usuário não tiver informado uma região, mantenha o nome como fornecido em address e defina location_bias para a área pretendida em vez de adivinhar uma região.

7. compute_alternative_routes (booleano, OPCIONAL): defina como true somente quando o usuário pedir opções ou alternativas de trajeto. O padrão é false, que retorna apenas o trajeto recomendado.

8. include_polyline (booleano, OPCIONAL): defina como true somente quando a geometria do trajeto (encoded_polyline) for necessária. O padrão é false.

Instruções para chamada de ferramenta:

• Se a origem ou o destino estiverem ausentes, você PRECISA pedir esclarecimentos ao usuário antes de chamar a ferramenta.
• Para perguntas como "Qual é a distância de A até B?", use B como origin e A como destination.

Exemplo de chamada de ferramenta: {"origin":{"address":"Torre Eiffel"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Museu do Louvre"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

Instruções para resposta:

• Quando rotas alternativas são solicitadas, elas são ordenadas da mais para a menos recomendada.
• Se routes estiver vazio, informe ao usuário que nenhuma rota foi encontrada. Não adivinhe um trajeto.
• Para encontrar lugares ao longo de um trajeto do DRIVE, transmita o retrieval_token do trajeto para search_along_route. O token é válido por 10 minutos.
• Apenas declare os fatos retornados pela ferramenta. NÃO invente navegação guiada, linhas de transporte público, estações, plataformas ou baldeações.
• A saída embasada precisa ser atribuída à fonte usando o campo attribution de cada rota, quando disponível.

Chame essa ferramenta quando o usuário quiser encontrar lugares, empresas ou pontos de interesse ao longo de um trajeto de viagem (por exemplo, "postos de gasolina no meu caminho para Tahoe", "cafeterias entre SF e San Jose"). Chamar essa ferramenta tem um custo maior do que search_places. Por isso, use search_places ao pesquisar perto de um único local, em vez de ao longo de um trajeto.

Requisitos de entrada (CRÍTICOS):

1. text_query (string - OBRIGATÓRIO): uma descrição em linguagem natural do que pesquisar ao longo do trajeto.

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

2. Especificação de rota (OBRIGATÓRIO: forneça exatamente UMA das seguintes opções):

   • retrieval_token (string): o retrieval_token retornado por uma chamada compute_routes anterior para um trajeto DRIVE. Prefira essa opção sempre que o trajeto já tiver sido calculado. O token é válido por 10 minutos.
   • route_endpoints (objeto): o origin e o destination da rota. Cada um precisa ser fornecido usando address, lat_lng ou place_id.
     • Exemplo: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}.
   • encoded_polyline (string): uma polilinha codificada que representa um trajeto DRIVE.

3. travel_mode (tipo enumerado - OPCIONAL): DRIVE (padrão), WALK ou BICYCLE. WALK e BICYCLE só são compatíveis com route_endpoints. TRANSIT não é compatível.

4. routing_preference (tipo enumerado - OPCIONAL):

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (padrão): calcula o trajeto e os desvios sem trânsito em tempo real. Latência mais baixa.
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: usa as condições de trânsito em tempo real quando disponíveis. Não há suporte para WALK ou BICYCLE. Defina isso APENAS quando o usuário perguntar sobre trânsito, congestionamento ou tempos de desvio ajustados ao trânsito. A latência é maior.

5. include_extended_details (booleano, OPCIONAL): defina como true somente quando a solicitação exigir insights de avaliações qualitativas, itens de menu ou ofertas específicas, atmosfera, dicas ou movimento de visitantes, disponibilidade de carregador de VE, preços de combustível ou outros detalhes qualitativos avançados. O padrão é false. Ativar essa opção pode aumentar a latência.

6. language_code (string - OPCIONAL): o idioma do resumo dos resultados e dos Place Details, por exemplo, en, ja, en-US. O valor padrão é en-US.

7. region_code (string - OPCIONAL): o código regional CLDR Unicode do usuário, por exemplo, US, CA.

Instruções para chamada de ferramenta:

• Cada resultado inclui um detour_summary (quando disponível) que descreve a distância extra (localized_detour_distance) e, a menos que o trajeto tenha sido fornecido como encoded_polyline, o tempo extra (detour_duration) incorrido ao parar nesse local. Use-a para comparar opções.
• A resposta summary pode conter citações baseadas em zero (por exemplo, "[0]") que fazem referência a entradas em results.
• A saída embasada precisa ser atribuída à fonte usando o campo attribution de cada results[].place, quando disponível.

Resolve uma lista em lote de consultas de locais específicos (nomes de pontos de referência ou endereços exatos) em IDs de lugar canônicos do Google Maps.

Requisitos de entrada (CRÍTICOS):

1. queries (matriz de objetos - OBRIGATÓRIO): uma lista de consultas de local para resolver. É possível especificar até 20 consultas.

   • Cada objeto de consulta precisa ter:
     • text (string - OBRIGATÓRIO): a consulta de texto que representa um nome de lugar ou endereço específico a ser resolvido.
       • Exemplos: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

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

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

3. region_code (string - OPCIONAL): o código de região CLDR Unicode (código de país de duas letras, por exemplo, US, CA) do usuário para influenciar os resultados.

Instruções para chamada de ferramenta:

• Especificidade (CRÍTICO): as consultas precisam representar um nome ou endereço de lugar específico. Pesquisas genéricas como 'restaurants' ou nomes de redes como 'Starbucks' não são aceitos.
• NÃO chame essa ferramenta se as ferramentas downstream que você planeja invocar já aceitarem strings de endereço ou nome de lugar diretamente.

Salvar no Google Maps:

• A resposta inclui um campo save_to_maps_url: um único link do Google Maps com todos os lugares resolvidos.
• Quando o usuário quiser salvar, compartilhar ou abrir os lugares resolvidos como uma lista no Google Maps, apresente esse link para ele. NÃO construa esse link por conta própria.

Tratamento de erros (CRÍTICO):

• Essa é uma ferramenta de processamento em lote. Uma solicitação pode retornar "resultados mistos" (por exemplo, algumas consultas são resolvidas com sucesso, enquanto outras falham).
• A lista de saída de results é garantida para mapear 1:1 com os índices de entrada queries. Uma consulta com falha vai resultar em uma mensagem Result vazia (sem entity definido) no índice correspondente na lista results.
• Você PRECISA verificar o campo de mapa failed_requests na resposta para identificar qual índice de consulta específico falhou. A chave de failed_requests representa o índice com base em 0 da consulta com falha na solicitação. Não presuma que toda a chamada em lote falhou devido a uma falha parcial.

Resolve uma lista de URLs do Google Maps em IDs de lugar canônicos do Google Maps.

Quando chamar essa ferramenta (CRÍTICO):

• Use esta ferramenta quando o usuário fornecer um ou mais links ou URLs de compartilhamento do Google Maps (por exemplo, "https://maps.app.goo.gl/...", "https://www.google.com/maps/place/..." ou "https://maps.google.com/...") e precisa extrair os IDs de lugar canônicos.
• É possível especificar até 20 URLs para resolver em uma única solicitação em lote.

Requisitos de entrada (CRÍTICOS):

• urls (matriz de strings - OBRIGATÓRIO): a lista de URLs do Google Maps a serem resolvidos. Cada URL precisa ser um URL válido do Google Maps para um único lugar.

Salvar no Google Maps:

• A resposta inclui um campo save_to_maps_url: um único link do Google Maps com todos os lugares resolvidos.
• Quando o usuário quiser salvar, compartilhar ou abrir os lugares resolvidos como uma lista no Google Maps (por exemplo, coletar lugares compartilhados em uma conversa), apresente esse link para ele. NÃO construa esse link por conta própria.

Tratamento de erros (CRÍTICO):

• Essa é uma ferramenta de processamento em lote. Uma solicitação pode retornar "resultados mistos" (por exemplo, alguns URLs são resolvidos com sucesso, enquanto outros falham).
• A lista de saída de entities é garantida para mapear 1:1 com os índices de entrada urls. Uma resolução de URL com falha vai resultar em uma mensagem Entity vazia (nenhum campo definido) no índice correspondente na lista entities.
• Você PRECISA verificar o campo de mapa failed_requests na resposta para identificar qual índice de URL específico falhou. A chave de failed_requests representa o índice com base em 0 do URL com falha na solicitação. Não presuma que toda a chamada em lote falhou devido a uma falha parcial.