Catálogo de herramientas

Veinte herramientas: las diecinueve del catálogo de la especificación, más select_empresa, que se agregó bajo la regla de evolución aditiva porque una sesión de chat quiere un default de empresa.

Convenciones que comparten todas

• El primer argumento de cada herramienta con alcance de empresa es empresa.
• La idempotencia es trabajo del servidor, no del agente. Un cliente REST manda su propio Idempotency-Key; un agente MCP no debería tener que pensar en seguridad de reintento. El servidor genera y administra la llave por debajo — anclada al preview_id cuando la llamada vino de draft_document, o a un UUID nuevo por llamada — así que un reintento tras una conexión cortada reutiliza el folio ya asignado en vez de quemar un segundo.
• Los errores son errores REST. El contenido de error de una herramienta es el mismo objeto { type, code, message, param, doc_url, request_id, empresa } del sobre de errores, devuelto como contenido de error MCP.
• Plata, fechas y RUT usan exactamente las convenciones de la API: enteros en CLP, fechas civiles YYYY-MM-DD en America/Santiago, RUT canónico.

Emisión

draft_document devuelve receptor_incomplete con el campo exacto que falta, nunca una adivinanza silenciosa. emit_document puede devolver totals_mismatch si el agente mandó totales explícitos que no cuadran — la descripción de la herramienta le dice que nunca calcule totales a mano salvo que esté seguro, precisamente porque ese campo es una aserción, no una pista.

Recepción

Impuestos

confirm_total_payable sigue siendo obligatorio a través de la capa MCP. La API REST ya se niega a declarar sin él, y esa barrera vale doble aquí: obliga a que la cifra aparezca explícita en la llamada de herramienta, lo que obliga a que aparezca explícita en lo que el agente le diga a la persona antes de declarar.

El narrative de get_periodo_summary existe porque acertarle al vocabulario tributario en español —débito, crédito, remanente— es exactamente el tipo de cosa que un modelo generalista equivoca de forma sutil. La herramienta devuelve las cifras crudas y el párrafo listo para citar.

Cuenta

Las tres primeras son deliberadamente de solo lectura y escuetas. select_empresa está acotada para que no rompa el requisito de que el servidor sea capaz de operar sin estado: un argumento empresa explícito siempre gana, y perder la sesión pierde un default, no produce una respuesta equivocada.

Confirmación

Cómo vuelven los archivos

MCP le da a una herramienta dos formas de devolver un archivo: embebido como blob base64, o como un resource_link que el cliente busca solo si y cuando necesita los bytes. Facturia MCP siempre usa resource_link, nunca blobs embebidos.

// → get_document_file
{ "empresa": "77928532-4", "document_id": "doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N", "format": "pdf", "copy": "cedible" }

// ← contenido del resultado
[
  { "type": "text", "text": "Factura 33 folio 412 — copia cedible, enlace válido 10 minutos." },
  {
    "type": "resource_link",
    "uri": "https://ver.facturia.cl/l/3d9f2b8a1c?exp=1755184211",
    "name": "factura-33-412-cedible.pdf",
    "mimeType": "application/pdf"
  }
]

Tres razones:

• Economía de contexto. Un PDF firmado embebido en base64 puede ser cientos de kilobytes de contenido inyectado al contexto del modelo por un documento que nadie pidió que leyera en voz alta. Un enlace cuesta una frase.
• Compatibilidad de clientes. Las URL pdf_url / xml_url de la API REST exigen una llave. La mayoría de los hosts MCP no tienen forma de adjuntar el token OAuth de Facturia al resolver un resource link — ni deberían tener que sostenerlo.
• Más seguro que el default REST. get_document_file enciende el mecanismo que REST ya publica como opt-in (enlaces públicos firmados, con vencimiento, sin autenticación) y le acorta la vida a 10 minutos, con alcance de un solo documento y sin listar. Suficientemente corto para que un enlace pegado en un chat que la persona comparta después ya esté muerto; suficientemente largo para sobrevivir la vuelta por lo que sea que lo renderice.

Lo que no está en la superficie de agente

Crear una empresa, cargar un certificado, firmar un mandato, pedir CAF, administrar webhooks, la marca y las escrituras de caracterización del RCV quedan solo en REST y panel. Dos razones se apilan: son acciones puntuales o raras con una UI mucho mejor que un turno de chat (nadie quiere pegar la contraseña de un .pfx en una conversación con un agente), y el registro dinámico de cliente significa que el software que llama no está verificado como sí lo está una sesión del panel, así que las herramientas de mayor radio de daño por error son justamente las que conviene mantener fuera del alcance del agente.

Tampoco hay herramientas de anulación (credit_note) ni de reintento (retry) en este corte.