> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fhiron.cl/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools: Referencia

> Catálogo técnico de las 10 herramientas fhiron_*: costos, signatures y convenciones.

Página de referencia. Para ver **prompts naturales y outputs reales** de cada tool en el chat de Cursor / Claude / Windsurf, ir directo a [Ejemplos por tool](/mcp/ejemplos). La estrategia de cuándo elegir lint vs validate (y por qué importa) vive en [Skill CL Core: Routing por intent](/mcp/skill-cl-core#routing-por-intent).

`@fhiron/mcp-connector` expone **10 herramientas** con prefijo `fhiron_`. El prefijo evita colisión con la marca registrada FHIR® (HL7) y deja todo el namespace agrupado en cualquier cliente MCP.

Para que el modelo (y tú) las absorban rápido, están organizadas en tres categorías mentales según la intención:

* **Validar**: confirmar que un recurso cumple CL Core v1.9.4
* **Explorar**: entender el estándar, los perfiles y la terminología chilena
* **Reparar**: aplicar correcciones mecánicas

<Tip>
  Regla práctica: empieza siempre por **Explorar** si no tienes un recurso aún (`fhiron_get_example`, `fhiron_search_terminology`), después **Validar** lo que armaste, y solo cuando un issue trae `quickFix`, llama a **Reparar**.
</Tip>

## Mapa de herramientas

```mermaid theme={null}
flowchart TD
    ROOT([fhiron_*<br/>10 herramientas])

    ROOT --> V[Validar]
    ROOT --> E[Explorar]
    ROOT --> R[Reparar]

    V --> V1[fhiron_lint<br/>· offline · gratis]
    V --> V2[fhiron_validate<br/>· 1 crédito · principal]
    V --> V3[fhiron_validate_file<br/>· 1 crédito · lee .json]
    V --> V4[fhiron_validate_bundle<br/>· 1 crédito por entry]
    V --> V5[fhiron_score_endpoint<br/>· offline · escanea endpoint]

    E --> E1[fhiron_get_example<br/>· offline · scaffolding]
    E --> E2[fhiron_search_terminology<br/>· offline · DEIS·TFC·CIE-10]
    E --> E3[fhiron_explain_code<br/>· offline · pedagógico]
    E --> E4[fhiron_compare_profiles<br/>· 2 créditos · R4 vs CL Core]

    R --> R1[fhiron_apply_fix<br/>· offline · idempotente]

    classDef root fill:#1e1f24,stroke:#635BFF,stroke-width:2px,color:#fff
    classDef group fill:#1e1f24,stroke:#7C7BFF,stroke-width:1.5px,color:#fff
    classDef tool fill:#0f1115,stroke:#3a3a45,color:#cfcfd6

    class ROOT root
    class V,E,R group
    class V1,V2,V3,V4,V5,E1,E2,E3,E4,R1 tool
```

## Validar

Confirman que un recurso, un Bundle o un endpoint completo cumple CL Core. Cinco tools, escaladas de barata a costosa.

| Tool                     | Costo                                 | Cuándo usarla                                                                                            |
| ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `fhiron_lint`            | Gratis (offline)                      | Lint local determinístico antes de tocar la red. Atrapa los errores `cl-*` con `quickFix` mecánico.      |
| `fhiron_validate`        | 1 crédito                             | **Tool principal**: corre el lint local y luego HAPI server-side para slicing y terminología profunda.   |
| `fhiron_validate_file`   | 1 crédito                             | Igual que `fhiron_validate` pero leyendo un `.json` del filesystem. Evita pegar JSONs largos en el chat. |
| `fhiron_validate_bundle` | 1 crédito por entry validada (cap 50) | Bundle entry-by-entry contra HAPI. Devuelve matriz pass/fail agrupada por `resourceType`.                |
| `fhiron_score_endpoint`  | Gratis (no llama a Fhiron)            | Escanea un endpoint FHIR público y devuelve un FHIR Score 0–100 con grade A–F y recomendaciones.         |

<Warning>
  `fhiron_score_endpoint` bloquea automáticamente URLs hacia redes privadas, loopback y metadata cloud (localhost, 10.x, 172.16-31.x, 192.168.x, 169.254.x, 100.64-127.x, ::1, fe8x..feb, fc/fd, metadata.google.internal). Usa únicamente endpoints FHIR públicos.
</Warning>

Detalle de costo por canal, conteo de Bundle y casos de IA en batch en [Cómo se cuentan las validaciones](/conceptos/conteo-de-validaciones).

## Explorar

Para entender el estándar, ver ejemplos válidos y consultar terminología chilena. Todas son gratis y offline. La IA debe llamarlas **antes** de inventar un código o un perfil.

| Tool                        | Costo            | Cuándo usarla                                                                                                                                        |
| --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fhiron_get_example`        | Gratis (offline) | Devuelve un recurso CL Core válido listo para editar (Patient, Practitioner, Encounter, Condition, MedicationRequest, +9).                           |
| `fhiron_search_terminology` | Gratis (offline) | Busca en catálogos chilenos: comunas DEIS, establecimientos DEIS, ATC/TFC, CIE-10, CSTipoIdentificador.                                              |
| `fhiron_explain_code`       | Gratis (offline) | Explicación pedagógica de un código de error (`cl-enc-04`, `cl-medreq-02`, `hapi-error-terminology`, `mcp-quota-01`, etc.) con `why`, fix y ejemplo. |
| `fhiron_compare_profiles`   | 2 créditos       | Valida el mismo recurso contra FHIR R4 base **vs** CL Core en paralelo y devuelve el diff de errores.                                                |

## Reparar

Aplica correcciones mecánicas obtenidas desde un `issue.quickFix` devuelto por `fhiron_validate` o `fhiron_lint`.

| Tool               | Costo            | Cuándo usarla                                                                                                               |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `fhiron_apply_fix` | Gratis (offline) | Aplica un `quickFix` (RFC 6901 jsonPointer + replacement) sobre el JSON original. Idempotente: aplicar dos veces es seguro. |

## Estructura del feedback

Cada `issue` que devuelven las tools de **Validar** responde las cuatro preguntas pedagógicas (qué / dónde / por qué / cómo arreglar):

```jsonc theme={null}
{
  "code": "cl-enc-04",                                          // qué (estable, máquina-legible)
  "severity": "error",
  "path": "Encounter.status",                                   // dónde (FHIRPath)
  "message": "Encounter.status='complete' no pertenece al ValueSet EncounterStatus (binding required). Códigos válidos: planned · arrived · triaged · in-progress · onleave · finished · cancelled · entered-in-error · unknown.",
  "why": "FHIR R4 — required binding al ValueSet http://hl7.org/fhir/ValueSet/encounter-status. 'complete' es un valor que devuelven varios HIS legacy, pero no es FHIR; el binding required no admite códigos custom.",
  "profileUrl": "http://hl7.org/fhir/StructureDefinition/Encounter",
  "docsUrl": "https://docs.fhiron.cl/inspect/errores#cl-enc-04",
  "suggestion": "Mapear el estado interno del HIS a uno de los códigos del ValueSet (finished cuando la atención cerró, in-progress cuando está abierta, cancelled cuando se anuló).",
  "example": { "status": "finished" },
  "quickFix": {
    "title": "Reemplazar por código FHIR válido",
    "jsonPointer": "/status",
    "replacement": "finished"
  }
}
```

## Convención de nombres

Los nombres canónicos usan el prefijo `fhiron_` para diferenciarse de la marca registrada FHIR® (HL7) y para que cualquier cliente MCP agrupe visualmente las herramientas del connector. Los nombres no van a cambiar. Son parte del contrato público del paquete.