MCP Tools Reference: mapstools.googleapis.com

Herramienta: resolve_names

Resuelve una lista de lotes de búsquedas de ubicaciones específicas (nombres de lugares de interés o direcciones exactas) en IDs de lugar canónicos de Google Maps.

Requisitos de entrada (CRÍTICOS):

  1. queries (array de objetos - OBLIGATORIO): Es una lista de búsquedas de ubicación que se resolverán. Puedes especificar hasta 20 búsquedas.

    • Cada objeto de consulta debe tener lo siguiente:
      • text (cadena; OBLIGATORIO): Es la búsqueda de texto que representa un nombre de lugar o una dirección específicos que se deben resolver.
        • Ejemplos: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA' y 'Eiffel Tower, Paris'

  2. location_bias (objeto, OPCIONAL): Usa este parámetro para priorizar los resultados cerca de un área geográfica específica.

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

  3. region_code (cadena, OPCIONAL): Es el código regional CLDR de Unicode (código de país de dos letras, p.ej., US, CA) del usuario para sesgar los resultados.

Instrucciones para la llamada a la herramienta:

  • Especificidad (CRÍTICA): Las búsquedas deben representar un nombre o una dirección de lugar específicos. No se admiten búsquedas generales, como 'restaurants', ni nombres de cadenas, como 'Starbucks'.
  • NO llames a esta herramienta si las herramientas posteriores que planeas invocar ya aceptan directamente cadenas sin procesar de direcciones o nombres de lugares.

Cómo guardar en Google Maps:

  • La respuesta incluye un campo save_to_maps_url: un solo vínculo de Maps que contiene todos los lugares resueltos correctamente.
  • Cuando el usuario quiera guardar, compartir o abrir los lugares resueltos como una lista en Google Maps, muéstrale este vínculo. NO construyas este vínculo por tu cuenta.

Manejo de errores (CRÍTICO):

  • Esta es una herramienta de procesamiento por lotes. Una solicitud puede devolver "resultados mixtos" (p.ej., algunas búsquedas se resuelven correctamente, mientras que otras fallan).
  • Se garantiza que la lista de salida de results se asigna 1:1 con los índices de queries de entrada. Una consulta fallida generará un mensaje Result vacío (no se establece ningún entity) en su índice correspondiente en la lista results.
  • DEBES verificar el campo del mapa failed_requests en la respuesta para identificar qué índice de búsqueda específico falló. La clave de failed_requests representa el índice basado en 0 de la búsqueda fallida en la solicitud. No supongas que falló toda la llamada por lotes debido a una falla parcial.

En la siguiente muestra de código, se muestra cómo usar curl para llamar a la herramienta de MCP resolve_names.

Solicitud de cURL 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Es el mensaje de solicitud para ResolveNames.

ResolveNamesRequest

Representación JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Campos
queries[]

object (LocationQuery)

Obligatorio. Es una lista de las búsquedas de ubicación que se resolverán. Puedes especificar hasta 20 búsquedas.
locationBias

object (LocationBias)

Opcional. Es una región opcional para sesgar los resultados de la resolución. Si se especifica, los resultados de la resolución se sesgarán hacia las entidades que estén más cerca de esta región. Incluir location_bias o region_code suele proporcionar mejores resultados, ya que reduce el espacio de búsqueda.

Si se especifican location_bias y region_code, location_bias tiene prioridad sobre region_code.
regionCode

string

Opcional. Es un código de región opcional para sesgar los resultados de la resolución. Si se especifica, los resultados de la resolución se sesgarán hacia las entidades que se encuentran en la región especificada o cerca de ella. Debe ser un código de región CLDR. Por ejemplo, "US" o "CA". Incluir location_bias o region_code suele proporcionar mejores resultados, ya que reduce el espacio de búsqueda.

Si se especifican location_bias y region_code, location_bias tiene prioridad sobre region_code.

LocationQuery

Representación JSON 
{
  "text": string
}
Campos
text

string

Obligatorio. Es la búsqueda de texto que se resolverá en una entidad geoespacial específica en Google Maps, como un lugar o una dirección. Cuanto más específica sea la consulta, más precisa será la resolución. Por ejemplo, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" o "Torre Eiffel, París". Las búsquedas deben ser una dirección o el nombre de un lugar específicos. No se admiten ubicaciones generales, como el nombre de una cadena (p.ej., Starbucks) o una búsqueda como "restaurantes".

LocationBias

Representación JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Campos
Campo de unión type. Es el tipo de sesgo de ubicación. type puede ser solo uno de los parámetros siguientes:
viewport

object (Viewport)

Es un viewport definido por un cuadro delimitador.

Viewport

Representación JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Campos
low

object (LatLng)

Obligatorio. Es el punto más bajo de la ventana gráfica.
high

object (LatLng)

Obligatorio. Es el punto más alto de la ventana gráfica.

LatLng

Representación JSON 
{
  "latitude": number,
  "longitude": number
}
Campos
latitude

number

La latitud expresada en grados. Debe pertenecer al rango [-90.0, +90.0].
longitude

number

La longitud expresada en grados. Debe pertenecer al rango [-180.0, +180.0].

Esquema de salida

Es el mensaje de respuesta para ResolveNames.

ResolveNamesResponse

Representación JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Campos
results[]

object (Result)

Solo salida. Es la lista de entidades resueltas a partir de las búsquedas de ubicación. Se garantiza que se asignará 1:1 con los índices de queries de la solicitud. Una cadena vacía en el índice i indica que la resolución falló para esa búsqueda. Si la resolución falló, consulta el campo failed_requests para ver el estado del error.
failedRequests

map (key: integer, value: object (Status))

Solo salida. Mapa que comunica fallas parciales. La clave es el índice de la solicitud fallida en el campo queries. El valor es el estado de error que detalla por qué falló la resolución.

Un objeto que contiene una lista de pares "key": value. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Solo salida. Un vínculo para guardar todas las entidades resueltas correctamente en Google Maps

Resultado

Representación JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Campos
entity

object (Entity)

Solo salida. Es la entidad resuelta de la búsqueda de ubicación.
confidence

enum (Confidence)

Solo salida. Es el nivel de confianza de la resolución.

Entidad

Representación JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Campos
Campo de unión entity. Es el tipo de entidad resuelto. entity puede ser solo uno de los parámetros siguientes:
place

string

Es el nombre del recurso del lugar resuelto.

FailedRequestsEntry

Representación JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Campos
key

integer
value

object (Status)

Estado

Representación JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

El código de estado, que debe ser un valor enum de google.rpc.Code.
message

string

Un mensaje de error dirigido al desarrollador, que debe estar en inglés. Cualquier mensaje de error dirigido al usuario debe localizarse y enviarse al campo google.rpc.Status.details; o el cliente debe localizarlo.
details[]

object

Una lista de mensajes que contienen los detalles del error. Hay un conjunto común de tipos de mensajes para que usen las API.

Un objeto que contiene campos de un tipo arbitrario. Un campo adicional "@type" contiene una URI que identifica el tipo. Ejemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Cualquiera

Representación JSON 
{
  "typeUrl": string,
  "value": string
}
Campos
typeUrl

string

Identifica el tipo del mensaje serializado de Protobuf con una referencia de URI que consta de un prefijo que termina en una barra y el nombre de tipo completo.

Ejemplo: type.googleapis.com/google.protobuf.StringValue

Esta cadena debe contener al menos un carácter /, y el contenido después del último / debe ser el nombre completamente calificado del tipo en formato canónico, sin un punto inicial. No escribas un esquema en estas referencias de URI para que los clientes no intenten comunicarse con ellas.

El prefijo es arbitrario, y se espera que las implementaciones de Protobuf simplemente quiten todo hasta el último / inclusive para identificar el tipo. type.googleapis.com/ es un prefijo predeterminado común que requieren algunas implementaciones heredadas. Este prefijo no indica el origen del tipo, y no se espera que los URIs que lo contienen respondan a ninguna solicitud.

Todas las cadenas de URL de tipo deben ser referencias URI legales con la restricción adicional (para el formato de texto) de que el contenido de la referencia debe constar solo de caracteres alfanuméricos, escapes codificados como porcentaje y caracteres del siguiente conjunto (sin incluir las comillas inversas externas): /-.~_!$&()*+,;=. A pesar de que permitimos la codificación de porcentaje, las implementaciones no deben decodificarlas para evitar confusiones con los analizadores existentes. Por ejemplo, se debe rechazar type.googleapis.com%2FFoo.

En el diseño original de Any, se consideró la posibilidad de iniciar un servicio de resolución de tipos en estas URLs de tipos, pero Protobuf nunca implementó uno y considera que contactar estas URLs es problemático y un posible problema de seguridad. No intentes comunicarte con URLs de tipo.
value

string (bytes format)

Contiene una serialización de Protobuf del tipo que describe type_url.

String codificada en base64.

Confianza

Es el nivel de confianza de la resolución.

Enums
CONFIDENCE_UNSPECIFIED Valor predeterminado Este valor no se usa.
MEDIUM La confianza media indica que es probable que la resolución sea correcta, pero puede haber otros candidatos.
HIGH La confianza alta indica que la resolución es correcta y representa una entidad geoespacial específica (p.ej., un lugar específico).

Anotaciones de herramientas

Las anotaciones de herramientas se envían a los clientes de MCP para describir el riesgo básico de una herramienta determinada. La mayoría de los clientes tratan estas sugerencias como no confiables, pero se pueden usar para decidir cuándo se le puede enviar un mensaje de confirmación a un usuario.

Junto con la cadena de título, se definen las siguientes sugerencias booleanas:

  • readOnlyHint: Si es verdadero, la herramienta no modifica su entorno. Valor predeterminado: false.
  • destructiveHint: Si es verdadero, la herramienta puede realizar acciones destructivas. Si es falso, la herramienta solo puede realizar acciones aditivas. Valor predeterminado: true.
  • idempotentHint: Si es verdadero, llamar a la herramienta varias veces con los mismos argumentos no tendrá ningún efecto adicional en su entorno. Valor predeterminado: false.
  • openWorldHint: Si es verdadero, la herramienta puede interactuar con un "mundo abierto" de entidades externas. Si es falso, la herramienta solo puede interactuar con entidades internas. Por ejemplo, una herramienta de búsqueda web sería de mundo abierto, mientras que una herramienta de memoria no lo sería.

Pista destructiva: ❌ | Pista idempotente: ❌ | Pista de solo lectura: ✅ | Pista de mundo abierto: ❌