> For the complete documentation index, see [llms.txt](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/referencias-tecnicas/herramientas.md).

# Herramientas del agente

El agente Taína expone ocho herramientas principales para recuperar información del catálogo de servicios gubernamentales y supervisar el estado del sistema. Cada herramienta devuelve strings JSON listos para que el LLM los procese y genere respuestas en lenguaje natural.

## Catálogo de herramientas

| Herramienta                   | Propósito                                                | Parámetros clave                            |
| ----------------------------- | -------------------------------------------------------- | ------------------------------------------- |
| `list_services`               | Buscar servicios por nombre, institución o palabra clave | `nombre`, `institucion`, `keyword`, `limit` |
| `get_service_overview`        | Obtener la descripción principal de un servicio          | `service_id`                                |
| `list_service_variations`     | Listar variaciones con requisitos y costos               | `service_id`, `categoria`, `limit`          |
| `get_service_locations`       | Recuperar oficinas, horarios y teléfonos                 | `service_id`, `limit`                       |
| `get_service_digital_channel` | Obtener pasos y URLs de trámites en línea                | `service_id`                                |
| `get_service_contact`         | Devolver correos y números oficiales                     | `service_id`                                |
| `ask_knowledge_base`          | Búsqueda semántica en los índices RAG                    | `query`, `service_id`, `top_k`              |
| `get_current_date`            | Fecha actual controlada (para validaciones)              | Sin parámetros                              |

## Firmas destacadas

```python
async def list_services(
    nombre: Optional[str] = None,
    institucion: Optional[str] = None,
    keyword: Optional[str] = None,
    limit: int = 5,
) -> str:
    ...

async def get_service_overview(service_id: str) -> str:
    ...

async def ask_knowledge_base(
    query: str,
    service_id: Optional[str] = None,
    top_k: int = 5,
) -> str:
    ...
```

## Parámetros adicionales y filtros

* `list_services`: admite combinaciones de filtros (`nombre`, `institucion`, `keyword`) y limita resultados con `limit`.
* `list_service_variations`: permite filtrar por `categoria` o limitar el número de variaciones (`limit`).
* `get_service_locations`: soporta filtros geográficos (`provincia`, `municipio`) además de `limit`.
* `ask_knowledge_base`: acepta `service_id` opcional para enfocarse en un servicio específico e incluye `top_k` para ajustar la cantidad de documentos recuperados por tipo de índice (`servicios`/`servicios_qa`).

## Manejo de placeholders

Cuando la base de datos carece de información oficial para un servicio, las herramientas devuelven objetos con `"placeholder": true`. El LLM debe usar esta señal para comunicar al ciudadano que el servicio no tiene datos disponibles y sugerir el canal alternativo (`*462` o `gob.do`).

## Flujo conversacional recomendado

1. **Identificar el servicio**: Llamar a `list_services` con el nombre o institución mencionada.
2. **Presentar panorama general**: Usar `get_service_overview` para describir el servicio.
3. **Explorar variaciones**: Ejecutar `list_service_variations` y explicar costos/requisitos.
4. **Compartir información operativa**: Usar `get_service_locations`, `get_service_digital_channel` y `get_service_contact`.
5. **Manejar datos faltantes**: Si una respuesta tiene `placeholder = true`, informar y ofrecer asistencia humana vía \*462.

Para la documentación completa de cada herramienta, consulta la [referencia de herramientas](/taina-agente-ia-ogtic/referencias-tecnicas/api/tools.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/referencias-tecnicas/herramientas.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.