Buenas prácticas para agentes

Si construyes un agente, un bot o una integración que usa el servidor MCP (o la API REST desde un modelo de lenguaje), estas pautas hacen que sus respuestas sean correctas, verificables y respetuosas con el servicio. El servidor ya envía un resumen de ellas como instrucciones al conectarse.

1. Los precios no son en tiempo real

Los precios son los que las gasolineras comunican al Ministerio y se actualizan dos veces al día (hacia las 8:00 y las 20:00, hora peninsular). El precio del surtidor puede haber cambiado desde entonces.

Di siempre de cuándo son los datos, con meta.last_updated convertido a hora de Madrid: «según los datos del Ministerio de hoy a las 8:12…».
No escribas «ahora», «en este momento» ni «en tiempo real».
Si meta.stale es true, los datos pueden ser de la actualización anterior: menciónalo.

2. Cita la fuente y enlaza

Cada resultado trae meta.attribution y meta.web_url. Incluye en la respuesta la fuente (Gasolina hoy, con datos del Ministerio para la Transición Ecológica y el Reto Demográfico) y el enlace a web_url; para gasolineras concretas, el web_url de cada una. Es la condición de la licencia CC BY 4.0 y permite al usuario comprobar el dato (Atribución y licencia).

3. Primero `search_places`

Los nombres son ambiguos («Valencia» es una ciudad, una provincia y una comunidad; «Santiago» hay varios). Antes de pedir precios de un lugar que el usuario ha nombrado, llama a search_places y usa el level y el code (o el station_id) del resultado. No inventes códigos: el code de un municipio no es su código INE.

4. Elige la herramienta más concreta

El usuario pregunta por…	Herramienta
Lo más barato en un sitio	`find_cheapest_fuel` (con `level` + `code`, o con `lat` + `lng`)
Lo más cercano a un punto	`find_fuel_near` con `sort: "distance"`
Un viaje de A a B	`find_fuel_along_route` (con puntos intermedios) y `calculate_trip_cost`
Una autovía concreta	`find_fuel_on_road`
Una media o una comparación	`get_fuel_prices`, `compare_regions`, `compare_brands`
La evolución	`get_price_history`, `get_monthly_report`
Una duda («¿qué es el E10?»)	`search_content` y, si hace falta, `get_article`
Impuestos	`explain_fuel_price`

5. Respeta los límites

Como mucho 30 llamadas a herramientas por minuto (y 60 mensajes) por IP. Un agente no necesita más para una conversación.
No recorras España provincia a provincia: compare_regions ya da el ranking completo en una llamada.
Pide solo los resultados que vas a usar (limit), no 50 si vas a mostrar 5.
Si recibes 429, espera lo que indique Retry-After (60 segundos) antes de volver a intentarlo.
Para análisis masivos, usa los datos abiertos, no el MCP.

Detalles en Límites de uso.

6. Canarias, Ceuta y Melilla

No pagan el Impuesto sobre Hidrocarburos: sus precios son más bajos por fiscalidad, no por la gasolinera. En los rankings de toda España van aparte salvo include_low_tax: true. Si el usuario está allí, busca dentro de su territorio; si compara con la península, explícalo.

7. No opines sobre marcas ni gasolineras

Los datos son del Ministerio: compara precios y calcula diferencias, pero no valores calidad ni recomiendes marcas sin datos. Los hechos de cada marca (compare_brands con brands) llevan sus fuentes: cítalas.

8. Resultados recortados y errores

Si un resultado trae truncated: true, las listas se han recortado a 10 elementos para no saturar el contexto: pide menos (limit) o filtra más.
Si una herramienta devuelve isError: true, lee el código (PROVINCE_NOT_FOUND, INVALID_PARAMETER…) y corrige los argumentos; no repitas la misma llamada. Ver Errores.

Fuente de los datos: Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras). Datos de la API y del servidor MCP con licencia CC BY 4.0: cita Gasolina hoy y la fuente.