This server provides an open-source interface for AI agents to interact with the Chilean SII (Servicio de Impuestos Internos) tax systems, offering comprehensive read-only access to tax documents and a write operation (currently broken) for issuing DTEs through the MIPYME free invoicing portal. Most capabilities require a digital certificate, while the MIPYME emission tool uses a tax password.
MIPYME Free Invoicing Portal
List companies the authenticated user can operate on the portal.
Query history of issued DTEs (electronic tax documents) with filters (folio, date, type, recipient).
⚠️ Emit a new DTE (invoice, credit note, etc.) – likely inoperative as of 2026-08-03.
DTE Queries (requires digital certificate)
List issued tax documents and received tax documents, filterable by date range, document type, and counterparty.
Retrieve full detail of a specific issued or received document by type, folio, and issuer RUT.
Boletas de Honorarios (requires digital certificate)
List issued or received freelance honorarium boletas for a specified month (with amounts and retention details).
Get an annual summary of issued honorarium boletas, showing monthly totals and statuses.
Personal & Real Estate (requires digital certificate)
List real estate properties associated with the authenticated person, including commune, address, fiscal valuation, and ownership percentage.
Session Management
Close the active SII session to avoid simultaneous session limits.
All operations except DTE emission are read-only and rely on official SII portals; data accuracy may vary per authorized companies.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-sii list issued tax documents from last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP open source para el Sistema de Facturación Gratuito del SII (mipyme.sii.cl). Permite a agentes IA (Claude, etc.) consultar documentos tributarios emitidos y recibidos.
Node.js 24+
agent-browser instalado globalmente: npm install -g agent-browser && agent-browser install
Certificado digital del SII instalado en el keychain del sistema (para operaciones marcadas con *)
Related MCP server: @integradte/mcp
npm install
npm run buildYa no hay una única credencial fija por proceso. Antes de llamar cualquier tool de consulta hay que abrir sesión para el RUT que se va a usar:
sii_iniciar_sesion(rut, clave) — autentica al SII con el RUT y la clave
tributaria de esa persona. La credencial vive sólo en memoria del proceso
(no se persiste a disco) y queda asociada a ese rut. Repetir la llamada
con el mismo RUT no abre una sesión nueva mientras la anterior siga
vigente (dentro de 2 horas) — abrir sesiones de más agota el límite del
SII para ese RUT.
Cualquier otra tool (sii_bhe_resumen, sii_dte_list_documentos_emitidos,
sii_rcv_resumen, etc.) recibe rut como su primer parámetro
obligatorio y opera sobre la sesión que abrió el paso anterior. Si no
hay sesión iniciada para ese RUT, la tool devuelve
{ "ok": false, "error": "SESION_NO_INICIADA" } en vez de autenticar
sola — no hay auto-login implícito.
sii_cerrar_sesion(rut) — cierra la sesión en el SII y olvida la
credencial de ese RUT. Conviene llamarla siempre al terminar: el SII
limita cuántas sesiones simultáneas puede tener un RUT y las bloquea al
superarlas (error 01.01.190.500.720.27).
Esto permite operar varios RUT en paralelo desde el mismo proceso, cada uno con su propia credencial y su propia sesión (cookie jar independiente).
Limitación actual: sii_iniciar_sesion sólo acepta rut + clave
(autenticación por clave tributaria, que corre por navegador). No hay hoy
forma de autenticar con certificado digital por esta vía. Las tools que
consultan por HTTP en vez de navegador (sii_bhe_*, sii_rcv_*,
sii_dte_*, sii_renta_*, sii_mipyme_list_*) necesitan el archivo de
cookies que sólo produce la autenticación con certificado — una sesión
abierta con clave vía sii_iniciar_sesion no lo genera, y esas tools van a
fallar (RequiereCertificado) para un RUT autenticado así. Hoy funcionan sin
problema con sii_iniciar_sesion las tools que operan por navegador:
sii_persona_list_bienes_raices y sii_mipyme_emitir_dte.
Variables de entorno (crear .env o configurar en Claude Desktop):
# RUT de la persona natural autorizada (no el RUT de la empresa). Requerida
# para que el proceso arranque, aunque ya no se usa para autenticar tools:
# la autenticación de tools pasa por sii_iniciar_sesion(rut, clave).
SII_RUT=12345678
# RUT de la empresa a operar (requerido si la persona opera múltiples empresas).
# Se sigue usando como fallback cuando la tool no recibe empresaRut.
SII_EMPRESA_RUT=22222222
# Sólo para EMITIR DTE en el portal mipyme: la clave del certificado digital que
# el contribuyente tiene cargado EN EL SII (el "certificado centralizado"), con
# la que el SII firma el documento del lado servidor.
SII_CERT_CLAVE_SII=claveDelCertCargadoEnElSiiSII_CERT_CLAVE_SII no se deriva de SII_CERT_PASSWORD, aunque parezca lo
mismo. El certificado cargado en el SII puede ser otro archivo, o el mismo
cargado con otra clave — y en ese segundo caso comparar los certificados diría
"coinciden" mientras la clave sigue sin servir. Si en tu caso son la misma
clave, configurá las dos variables con el mismo valor: queda explícito y no
depende de una suposición del código.
Sin esta variable, emitir falla pidiéndola; todo lo demás (consultas y la previsualización de un DTE) funciona igual.
Verificar el servicio entero necesita cuatro credenciales, no una: lo que un contribuyente puede consultar depende de qué es y de cómo factura, y el certificado es además otra forma de entrar.
Perfil | Qué es | Verifica |
| Persona natural | BHE emitidas y recibidas, bienes raíces, renta |
| Inscrito en Facturación Gratuita del SII | El portal mipyme entero |
| Factura con software de mercado | RCV, DTE, F29 |
| Certificado digital ( | Lo mismo que su titular, más firmar: |
El de certificado no es otro contribuyente sino la otra forma de autenticar, y
es la única con la que se puede firmar. El .env guarda la ruta del .pfx
—es un binario de varios KB— y la conversión a base64 que piden las rutas la hace
perfilesVerificacion.ts.
El de mipyme no es intercambiable: si el RUT no está inscrito en Facturación
Gratuita, el selector de empresas del portal viene sin una sola opción y no hay
nada que consultar. Eso no se ve en el .env ni en ningún otro lado hasta que se
intenta, y por eso existe:
npx ts-node src/scripts/clasificarCredencial.ts # los que estén cargados
npx ts-node src/scripts/clasificarCredencial.ts mipyme # uno en particularSondea las rutas REST de producción y dice para qué sirve realmente cada credencial. Conviene correrlo antes de empezar una ronda, no a la mitad.
perfilesVerificacion.ts no sustituye un perfil por otro: si falta el que se
pide, falla diciendo cuál. Un fallback haría correr la verificación contra un
contribuyente distinto, y ahí ni el verde ni el rojo dicen nada sobre lo que se
quería probar.
Ver .env.example para la plantilla completa.
SII_CLAVE / SII_CERT_PATH (una sola credencial por proceso)SII_CLAVE=mipassword
# o, con precedencia sobre la clave:
SII_CERT_PATH=/ruta/al/certificado.pfx
SII_CERT_PASSWORD=passwordDelCertEstas variables ya no son la forma de autenticar las tools: el código
que las lee (getConfig()/validateEnv()) sigue existiendo, pero ninguna
tool de consulta pasa por ahí — todas usan la credencial que dejó
sii_iniciar_sesion para el rut de la llamada. Quedan documentadas acá
sólo porque npm run validate-cert (más abajo) las sigue leyendo para
validar el .pfx fuera del flujo de sesión.
Antes de usar SII_CERT_PATH/SII_CERT_PASSWORD, puedes verificar que el .pfx
existe y que la contraseña lo desbloquea correctamente (sin exponer el subject/issuer,
que suele contener datos personales):
npm run validate-certLee SII_CERT_PATH y SII_CERT_PASSWORD desde el entorno (.env) y termina con
código 0 si el certificado es válido, o 1 con un mensaje de error si no.
Agregar en claude_desktop_config.json:
{
"mcpServers": {
"sii": {
"command": "node",
"args": ["/ruta/a/mcp-sii/dist/src/index.js"],
"env": {
"SII_RUT": "12345678",
"SII_EMPRESA_RUT": "22222222"
}
}
}
}SII_RUT sigue siendo requerida para que el proceso arranque, pero ya no
autentica nada por sí sola. Una vez conectado, autenticá cada RUT con el que
vayas a operar llamando sii_iniciar_sesion(rut, clave) desde el chat antes
de pedir cualquier consulta.
Todas las consultas son de solo lectura, con una única excepción marcada como tal.
Todas reciben rut como primer parámetro — ver
Autenticación: sesión por RUT.
Tool | Descripción |
| Autentica un RUT con su clave tributaria. Necesaria antes de llamar cualquier otra tool con ese RUT |
| Cierra la sesión en el SII para ese RUT y olvida su credencial (conviene al terminar) |
Tool | Descripción |
| Empresas que la persona puede operar en este portal |
| Historial de DTE emitidos por este portal, de a 100 por página |
| DTE recibidos por la empresa, con el estado del acuse |
| Borradores guardados, con todos los campos del SII |
| Emite un DTE. Acto tributario real e irreversible — ver la advertencia abajo |
Tool | Descripción |
| Resumen por tipo de documento del período, con detalle opcional |
| Ídem, del lado recibido |
| Detalle de un documento emitido |
| Detalle de un documento recibido |
| Si un DTE (emisor, tipo, folio) fue recibido por el SII |
| Si emisor, receptor, folio, fecha y monto coinciden con lo informado al SII |
| Estado del F29 (IVA mensual) de un período |
sii_dte_validez y sii_dte_verificar eran consultas públicas del SII y hoy
están detrás del login, así que van con sesión. La segunda es la que sirve para
validar una factura recibida antes de pagarla: datosCoinciden es el veredicto,
y el texto del SII distingue "Datos coinciden con los registrados" de "datos NO
coinciden" con casi las mismas palabras — se midió con el mismo documento y el
monto cambiado en un peso.
sii_f29_estado_declaracion consulta la declaración de IVA de un período
(AAAAMM): folio, estado, observaciones, fecha y moneda. El PDF del formulario
compacto —donde están todos los montos— se pide aparte por REST
(/v1/f29/formulario-compacto). La Consulta Integral del SII es una app GWT sin
API pública: el servicio habla su protocolo GWT-RPC directamente, así que esta
consulta es más frágil que las demás —si el SII recompila la app cambia un
hash interno y hay que re-relevarlo—, y falla explícito cuando eso pasa.
Tool | Descripción |
| Registro de Compras y Ventas, resumen del período |
| Registro de Compras y Ventas, documento por documento |
| Catálogo de los 46 tipos de documento del registro |
| Genera el detalle del RCV en background para volúmenes grandes |
| Estado (CREADO/EN PROCESO/TERMINADO) de una solicitud async del RCV |
| Empresas que el RUT puede consultar en el RCV |
| Formulario 22 completo de un año tributario |
| Estado de la declaración de renta |
sii_rcv_detalle devuelve 26 campos por documento, no sólo los montos
básicos: además de neto, exento, IVA y total, informa el IVA no recuperable con
su código, el neto e IVA de activo fijo, el IVA de uso común, el impuesto sin
derecho a crédito, el IVA no retenido, los tres montos de tabaco, las fechas de
recepción y de acuse, y el tipo de transacción. Para cuadrar un F29 no son
opcionales: el IVA no recuperable, el de uso común y el de activo fijo cambian el
crédito fiscal. sii_rcv_resumen informa los dos primeros por tipo de documento
y en los totales.
Dos criterios al leer esos campos. Los montos vienen en 0 y los códigos en
null: el SII manda 0 cuando el concepto no aplica al documento, y ahí el cero
ES el dato, mientras un código en 0 no sería "código cero" sino "no hay". Y
fechaRecepcion trae hora y fechaEmision no (23/06/2026 12:51:37 contra
23/06/2026): son dos formatos distintos en la misma fila, tal como los manda el
SII, y no se normalizan para que la diferencia se vea en vez de descubrirse
parseando.
sii_mipyme_list_borradores sale de otra aplicación del SII, no del portal
clásico: mipymeinternetui, con su propia API. Devuelve los campos con los
nombres del SII (EFXP_*) sin renombrar, porque un borrador trae decenas que
dependen del tipo de documento y elegir cuáles exponer sería adivinar qué
necesita quien consulta. Verificado con un borrador real: ehdr_CODIGO es el
código y ptdc_CODIGO el tipo de documento.
Los borradores cuelgan de la empresa activa, así que empresa_rut importa:
sin él, un RUT que opera varias empresas recibe los borradores de la que dejó la
consulta anterior. No es teórico — con la empresa sin fijar, las cinco empresas
de prueba devolvían cero borradores, y un listado vacío se lee como "no tenés
borradores" en vez de "preguntaste por otra empresa".
Tres cosas del catálogo de apigateway no se homologaron, y no por falta de tiempo:
borrador-pdf. Depende de tener un borrador; sin ninguno no hay nada que
relevar ni con qué verificar.
info-contribuyente. El formulario de emisión no expone ningún CGI de
consulta de contribuyente: los datos del receptor aparecen recién al
previsualizar, o sea que no hay una consulta separada que homologar.
El PDF de un documento existe sólo como ruta REST (POST /v1/mipyme/dte-pdf),
no como tool MCP, igual que el de BHE: un PDF en base64 dentro de una respuesta
MCP satura el contexto sin que el modelo pueda hacer nada con él. Se pide por el
codigo que devuelve el listado y no por el folio, que se repite entre
emisores y entre tipos de documento.
El respaldo XML (POST /v1/mipyme/respaldo-xml) es la fuente buena para
procesar documentos: devuelve el SetDTE firmado tal como lo entrega el
portal, con el detalle línea a línea (NmbItem, QtyItem, PrcItem,
MontoItem) y el giro del emisor (Acteco, GiroEmis) en campos. El PDF sirve
para mirar un documento; el XML, para clasificarlo sin parsear una maqueta de
impresión. Tampoco es tool MCP: un respaldo entero en el contexto del modelo no
le sirve de nada.
Dos cosas que definen su forma, las dos verificadas contra el SII:
El camino no es el que enlaza el menú. /Portal001/auth.html sólo redirige por
JavaScript a auth.cgi, que es el CGI que abre el contexto de descarga; después
van lista_documentos.cgi (fija la búsqueda) y download.cgi (entrega el XML).
Quedarse en el .html daba el falso negativo de que "el portal no ofrece XML".
El reCAPTCHA de esa pantalla no bloquea: el propio JavaScript manda el token
sólo si existe, y download.cgi responde sin él.
El SII no entrega más de 20 documentos por descarga, y el tope lo impone el
servidor, no el JavaScript. Un rango que lo exceda se parte al medio y cada
mitad se pide aparte, hasta que todas pasen; la respuesta trae un tramo por
descarga, cada uno un SetDTE válido por sí solo. No se concatenan: dos
SetDTE pegados no son XML bien formado, y unificarlos obligaría a reescribir
contenido firmado. Un día suelto con más de 20 documentos ya no se puede
partir por fecha y falla diciéndolo, en vez de devolver un respaldo incompleto
que se lee igual que uno completo.
sii_mipyme_list_dte_recibidos es el espejo de list_dte_emitidos y comparte su
forma, con el emisor como contraparte en vez del receptor. Trae algo que
sii_rcv_* no tiene: el estado del acuse (DTE Recibido Sin Reparos,
con Reparos), que es la respuesta que la empresa dio al documento.
sii_rcv_empresas_autorizadas no es lo mismo que sii_mipyme_list_empresas:
éstas son las empresas que el RUT puede consultar en el registro, y las de
mipyme las que puede operar en el portal de facturación gratuita. Un RUT
puede estar en una lista y no en la otra. Confundirlas llevaría a ofrecer
facturar por una empresa que sólo se puede mirar.
Tool | Descripción |
| Valor diario de la UF de un año |
| Dólar observado diario de un año |
| UTM, UTA e IPC por mes |
| Factores de corrección monetaria por mes |
| Tramos del impuesto único de 2ª categoría (art. 43) |
| Tramos del art. 52 bis |
Tool | Descripción |
| Tipos de vehículo de la planilla de un año |
| Marcas, opcionalmente por tipo |
| Modelos de una marca con versiones y años tasados |
| Tasación fiscal y permiso, por código SII o marca+modelo |
| Diccionario de siglas de equipamiento |
Tool | Descripción |
| Los ~670 códigos de actividad económica, filtrables por categoría, IVA y texto |
| Un código de actividad económica |
| Formato y dígito verificador de un RUT (aritmética, no consulta al SII) |
| La ficha del contribuyente autenticado según Mi SII |
Las tres primeras van sin credencial: la tabla de códigos es una página pública y
el verificador de RUT es módulo 11. sii_verificar_rut no dice si el RUT
existe —para eso está sii_contribuyente_situacion_tributaria—, sólo si está
bien formado. La categoría tributaria viene tal como la publica el SII ("1",
"2" o alguna letra como "G" que su tabla no explica); traducirla sería inventar.
sii_misii_datos_contribuyente lee el JSON que la home de Mi SII trae embebido
(DatosCntrNow): identificación, tipo y subtipo, segmento, glosa de actividad,
fechas, capital, direcciones vigentes y atributos (regímenes y autorizaciones con
su vigencia). No trae representantes, socios ni giros: esas secciones no se
pudieron relevar con datos.
Sin rut ni credencial, como indicadores. La fuente no es la consulta
interactiva del portal —exige un captcha propio del SII antes de cualquier
búsqueda— sino las planillas XLSX anuales que el SII publica (liv{año} para
livianos, pes{año} para pesados, desde 2020). La primera consulta de un año baja
la planilla entera (~7 MB, unos segundos) y las siguientes salen de memoria.
Livianos y pesados traen columnas distintas: pesados tiene carga y pasajeros y
no trae permiso (va en null); livianos al revés. El diccionario de siglas de
equipamiento está en /v1/vehiculos/equipamiento.
Ni estas tools ni las de vehículos reciben rut ni credencial, ni necesitan
sii_iniciar_sesion: el SII publica estas tablas abiertas. En REST viven bajo
/v1/indicadores/… y /v1/vehiculos/…, y siguen pasando por el auth de tenant y
el rate-limit, como todas.
Tres cosas al leerlas:
Un día que el SII no publicó no aparece, en vez de aparecer en cero. El dólar sólo trae días hábiles, y el año en curso llega hasta el último día publicado. Un cero en un tipo de cambio no es lo mismo que "no hay dato".
La corrección monetaria es triangular: un mes no tiene factor contra los
meses anteriores, así que muchas celdas vienen en null, y ese null
significa "no corresponde".
En los tramos de 2ª categoría, el tramo exento trae exento: true y sus
números en null, no en 0. Un factor 0 daría el mismo impuesto por un camino
que la tabla no dice. El art. 43 trae los cuatro períodos (MENSUAL, QUINCENAL,
SEMANAL, DIARIO) y el art. 52 bis sólo el mensual; el último tramo de cada
período no tiene tope, y ahí hasta va en null.
Los resultados se cachean en memoria por año e indicador. Un año ya cerrado no se vuelve a consultar nunca —el valor de la UF de un día pasado no cambia— y el año en curso se revisa cada seis horas. Cada consulta baja una página entera del SII, y el SII corta por volumen: sin caché, convertir cien montos a UF bajaría cien veces la misma tabla.
Tool | Descripción |
| Boletas de honorarios emitidas |
| Boletas de honorarios recibidas |
| Resumen anual de boletas emitidas |
| Resumen anual de boletas recibidas |
| Bienes raíces de la persona, con los códigos del catastro |
| Comunas del catastro con su código |
| Un bien raíz cualquiera por rol: avalúo y contribuciones |
| Copropietarios de un rol |
| Historial de certificados pedidos, con la url del PDF |
Los dos resúmenes anuales devuelven siempre los doce meses, en orden: un mes
sin actividad viene en cero y con los folios en null. Devolver sólo los meses
con boletas obligaba a interpretar una ausencia, y "no tuvo" se veía igual que
"no se pudo leer".
sii_bhe_resumen_recibidas no equivale a sumar sii_bhe_list_recibidas:
son dos CGI distintos del SII, y el anual informa una retención del
contribuyente que el informe mensual de recibidas no muestra. Para 07/2026 el
anual da 19.063 de retención y el mensual muestra "Retenido 0" en las cuatro
boletas — en la UI del portal y en la API por igual. Si necesitás la retención
de las boletas recibidas, sale de ahí y de ningún otro lado.
En ese informe, además, folioInicial y folioFinal vienen siempre en
null, por mes y del año. El portal no muestra folios ahí, y un rango no
significaría nada: cada boleta la folió un emisor distinto.
sii_bhe_list_recibidas pagina los meses de más de 100 boletas encadenando el
código de continuación del informe; no hay captura real de un mes así y la
garantía son los chequeos de integridad (conteo y duplicados). El detalle está en
la guía de integración, sección de limitaciones.
Bienes raíces ya no usa navegador: la SPA del portal tiene detrás una API
REST/JSON (/app/vica/{rut}/v1/…) y el servicio le pide lo mismo que la SPA.
Sin esa cookie del contexto /app que deja el handshake de la SPA, la API
responde cero bytes, no un error. Los certificados de avalúo
(/v1/bienes-raices/certificado-avaluo) y el PDF de una solicitud
(/v1/bienes-raices/documento) van sólo por REST: un PDF en base64 satura el
contexto del modelo. Pedir un certificado es una solicitud real que queda en
el historial del contribuyente; no es un acto tributario ni tiene costo, pero
tampoco es una lectura, y por eso no se cachea ni se reintenta solo.
sii_persona_list_bienes_raices funciona con la sesión que abre
sii_iniciar_sesion (clave, por navegador). El resto de las consultas por HTTP
—Consultas DTE, Impuestos y registros, boletas de honorarios y los listados de
mipyme— aceptan clave tributaria o certificado digital: las dos producen el
cookie jar que esa vía necesita. La única que sigue exigiendo certificado es
sii_mipyme_emitir_dte cuando firma, porque firmar un DTE necesita el
certificado de verdad y no basta una sesión autenticada.
POST /v1/contribuyente/situacion-tributaria con { rut }. Es la única ruta del
adaptador que no lleva credencial del contribuyente: el SII publica esta
consulta abierta, así que se puede preguntar por cualquier RUT. Sigue pasando por
el auth de tenant y el rate-limit del servidor, como todas.
Devuelve razón social, si presenta inicio de actividades y desde cuándo, si es empresa de menor tamaño (pro-pyme), si declara en moneda extranjera, y las actividades económicas vigentes con su código, giro, categoría y si afectan IVA.
Tres cosas que conviene saber:
El dígito verificador se valida antes de consultar. El SII resuelve por el
cuerpo del RUT, así que un DV mal escrito devolvería los datos del
contribuyente con el DV corregido — o sea que un RUT inválido saldría como
válido. Con DV incorrecto la respuesta es 400, y el detalle dice cuál era
el que correspondía.
Hay caché en memoria de 24 horas por RUT. Esta consulta le pega dos veces a
zeus.sii.cl (captcha más informe) y el dato casi no cambia. Sólo se cachean
los éxitos: un fallo del portal, o un RUT que todavía no tiene datos, se
vuelven a consultar.
observaciones y documentos_timbrados no se emiten todavía: no hay una
captura del informe que los traiga, y escribir el parseo a ciegas devolvería
datos plausibles que nadie revisaría. Está anotado en la spec del endpoint.
La migración del portal mipyme a HTTP directo (2026-08-03) cambió dos cosas para quien ya usaba estas tools:
sii_mipyme_list_empresas y sii_mipyme_list_dte_emitidos ahora requieren
certificado digital. Antes corrían por navegador y aceptaban clave tributaria.
El camino HTTP necesita el archivo de cookies que sólo produce la autenticación
con certificado, igual que el resto de las consultas. Fallan de entrada, con el
mensaje que dice qué configurar. sii_mipyme_emitir_dte sigue por navegador y
sigue aceptando clave.
limit ya no existe en sii_mipyme_list_dte_emitidos: se reemplaza por
pagina. El CGI entrega de a 100 documentos por página y recortar del lado
del cliente escondía que había más. La respuesta ahora informa pagina y
totalPaginas.
La resolución de la empresa no cambió: el parámetro gana, si no vino se usa
SII_EMPRESA_RUT, y si tampoco hay se resuelve sola cuando el RUT opera una única
empresa en el portal.
sii_mipyme_emitir_dte está probablemente inoperativa. Apunta a mipeDocAlta.cgi,
que responde 404 (medido el 2026-08-03). La ruta del portal es
mipeLaunchPage.cgi?OPCION=<tipo>&TIPO=4, pero no se corrigió sin relevar antes el
formulario que sirve: apuntarla a ciegas convertiría un fallo visible en un camino que
emite documentos tributarios reales con parámetros adivinados.
sii_dte_* y sii_rcv_* no son comparables. Responden preguntas distintas y sus
cifras no cuadran: Consultas DTE incluye guías de despacho, clasifica las facturas de
compra del lado emitido, y sus recibidos difieren de los del RCV. Ninguno está mal.
Cada aplicación del SII tiene su propia lista de empresas autorizadas. La de
sii_mipyme_list_empresas no coincide con la que habilitan el RCV o Consultas DTE.
Las rutas /v1/* responden siempre HTTP 200 —salvo 400 por body inválido— y el
resultado va en el cuerpo: {"ok": true, ...} o {"ok": false, "error": "..."}.
Lo que un consumidor necesita saber de cada código es si reintentar sirve:
| ¿Reintentar? | Cuándo aparece |
| No | El body no valida. Trae |
| No | El portal dijo explícitamente que la clave es incorrecta |
| No | El SII confirmó que el dato no existe. Trae |
| No | Un límite que ya conocemos: un descuadre entre lo que el SII informa y lo que se recupera, o un cambio de formato de un CGI. Trae |
| Sí, tras esperar | El RUT ya tiene demasiadas sesiones abiertas en el SII. Trae |
| Sí, esperando de verdad | El SII cortó las consultas por volumen (su propio error 429). Trae |
| Sí, en segundos | Nosotros estamos ocupados: demasiadas consultas de indicadores esperando turno. Trae |
| Sí | Todo lo demás: cola de espera del SII, portal caído, fallo de red |
LIMITE_SII es el que más cambia qué hacer: el SII tiene rate limiting propio y,
con muchas consultas al mismo portal en poco tiempo, corta ESE PORTAL ENTERO por
un rato — para todos. Reintentar de inmediato es lo que mantiene el corte: hay
que esperar minutos, no segundos, y bajar el ritmo. Los barridos internos ya van
con pausa por esto mismo (src/ritmoSii.ts).
Un detalle que cuesta diagnosticar: el SII no devuelve un status 429, devuelve una página HTML. Sin mirar el cuerpo es indistinguible del HTML del login —o sea de "la sesión expiró"— y las dos cosas piden lo contrario: una que esperes, la otra que reintentes reautenticando.
SESIONES_SIMULTANEAS se comporta igual que ERROR —reintentar sirve— y
existe por lo que permite decirle a la persona. Con ERROR sólo cabe "probá
de nuevo en unos minutos"; con éste se le puede decir que hay otra consulta en
curso sobre el mismo contribuyente, que es accionable: sabe que dejó otra
pestaña abierta o que un colega está mirando el mismo caso. Salía mezclado en
ERROR y eso mandaba a diagnosticar timeouts y problemas de red que no existían.
Los dos códigos con "no" que podrían confundirse:
CREDENCIALES_INVALIDAS se reserva para cuando el portal lo dice con esas
palabras. Un fallo transitorio sale como ERROR, nunca como credencial
inválida — si no, un consumidor que borra la credencial al recibirlo estaría
borrando claves que sí servían por una caída del SII.
LIMITE_CONOCIDO existe porque esos casos son permanentes y salían como
ERROR: el consumidor reintentaba en loop algo que nunca iba a funcionar.
npm test # correr tests
npm run dev # desarrollo con ts-node
npm run build # compilar TypeScriptnpm test usa el navegador mockeado y no toca la red. Existe además una suite
que le pregunta al portal de verdad, con su propio comando:
npm run test:e2eNecesita SII_RUT y SII_CLAVE en el .env; sin credenciales se saltea sola en
vez de fallar. Cubre dos cosas: que la clave correcta autentique y deje cookies
de sesión utilizables, y que un login que no puede tener éxito no se reporte
como exitoso. Ese segundo caso existe porque fue un bug real en producción
(validar-clave respondía ok:true con cualquier clave) y ningún test con el
navegador mockeado podía detectarlo: el criterio de éxito estaba mal, y el mock
contestaba lo que le habíamos enseñado a contestar.
Va separada de npm test a propósito. Cada test abre una sesión real, y el SII
limita las sesiones simultáneas por RUT y bloquea las claves con varios
intentos fallidos, así que no conviene que se dispare desde CI ni sin querer.
Hay un tercer caso, apagado por defecto, que manda una clave incorrecta al RUT
propio para verificar que se clasifica como CREDENCIALES_INVALIDAS:
SII_E2E_CLAVE_MALA=1 npm run test:e2eEs el único que ejercita esa clasificación de punta a punta, y también el único que acumula intentos fallidos sobre una cuenta real. Correlo puntualmente, no en loop.
Lista boleta por boleta las boletas de honorarios electrónicas emitidas por el RUT persona autenticado en un mes: folio, fecha, receptor de la boleta (en contraparteRut/contraparteNombre, con contraparteRol="receptor"), honorario bruto, retención del emisor y del receptor, total líquido y si está anulada. No requiere SII_EMPRESA_RUT: cuelga de la persona, no de la empresa.
| Name | Required | Description | Default |
|---|---|---|---|
| mes | Yes | Mes a consultar (1-12) | |
| anio | Yes | Año a consultar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the output fields (folio, fecha, contraparte, honorario bruto, retenciones, total líquido, anulada), the scope (per person, monthly), and an important behavioral trait (does not require company RUT). This goes beyond a simple 'list' and sets expectations for data content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely efficient: two sentences convey purpose, output fields, and a key distinction (person-level vs company-level). Every clause adds value, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (2 simple params, no output schema), the description adequately tells the agent what the tool returns and its scope. It doesn't describe error cases or pagination, but for a straightforward list with a defined field set, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions ('Mes a consultar', 'Año a consultar'). The description adds context that the month is the issuance month, but this is already implied. No additional parameter-level detail is needed, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Lists electronic fee invoices issued by the authenticated person's RUT in a month' with a precise verb and resource. It distinguishes from siblings by specifying 'emitidas' (issued) and explicitly noting it does not require SII_EMPRESA_RUT, which differentiates it from company-level tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it lists issued invoices for the authenticated person, and explicitly states when not to use it (no SII_EMPRESA_RUT needed). It doesn't name alternative tools but the sibling names (e.g., sii_bhe_list_recibidas) imply the counterpart, making usage intent clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista las boletas de honorarios electrónicas recibidas por el RUT persona autenticado en un mes: folio, fecha, emisor de la boleta (en contraparteRut/contraparteNombre, con contraparteRol="emisor"), honorario bruto, retención del receptor, total líquido y si está anulada. El SII no informa la retención del emisor en las recibidas, así que retencionEmisor viene en null. No requiere SII_EMPRESA_RUT: cuelga de la persona, no de la empresa.
| Name | Required | Description | Default |
|---|---|---|---|
| mes | Yes | Mes a consultar (1-12) | |
| anio | Yes | Año a consultar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that retencionEmisor is always null for received receipts due to SII behavior, which is a data quirk beyond the schema. It also states the authentication scope (persona, not empresa). Since no annotations are provided, this context is essential and well-addressed. It does not explicitly state the operation is read-only, but the listing verb implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with multiple clauses but every part contributes valuable info: purpose, fields, null field note, and auth scope. It is not excessively long and leads with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a complete picture for a list tool: what it lists, for whom, with which fields, and the null behavior. Since there is no output schema, enumerating the returned fields is critical and is done thoroughly. The auth note completes the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (anio, mes) are fully described in the JSON schema with ranges. The description only references them as 'en un mes' and does not add additional syntax or format details. Given 100% schema coverage, the description provides no extra value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing received electronic fee receipts (boletas de honorarios electrónicas) for the authenticated person's RUT within a specified month. It specifies the exact fields returned and distinguishes from emitted receipts by the word 'recibidas' and the sibling 'sii_bhe_list_emitidas'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that the tool operates at the persona level and does not require SII_EMPRESA_RUT, which helps users decide when to use this tool versus enterprise-level tools. However, it does not explicitly mention alternative tools by name or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resumen anual de las boletas de honorarios electrónicas emitidas por el RUT persona autenticado en el SII. Devuelve, por cada mes con actividad, el honorario bruto, la retención de terceros y del contribuyente, el rango de folios y cuántas boletas están vigentes o anuladas. No requiere SII_EMPRESA_RUT: cuelga de la persona, no de la empresa.
| Name | Required | Description | Default |
|---|---|---|---|
| anio | Yes | Año tributario a consultar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavior disclosure. It details the returned fields and scope, but does not mention authentication prerequisites (beyond the implied authenticated RUT), error handling, or whether the operation is read-only. This provides moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: it states the purpose, enumerates the output data, and clarifies the scope. Each sentence adds value without redundancy, making it both concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description explains the aggregate content per month and the dependency on the authenticated person. It lacks details on response format or edge cases (e.g., months with no activity), but this is a minor gap for a summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'anio' is fully described in the schema ('Año tributario a consultar'), covering 100% of parameter documentation. The description adds no additional parameter semantics, which is acceptable since the schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool provides an annual summary of electronic fee receipts (boletas de honorarios) for the authenticated person RUT, listing specific aggregated data per month. This distinguishes it from sibling list tools, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that the tool does not require SII_EMPRESA_RUT and is tied to the person rather than the company, which helps select it for personal RUT queries. However, it doesn't explicitly compare to sibling tools like sii_bhe_list_emitidas, so alternatives are implied rather than named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cierra la sesión abierta en el SII. El SII limita cuántas sesiones simultáneas puede tener un RUT y las bloquea al superarlas (error 01.01.190.500.720.27), así que conviene cerrarla al terminar.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds useful behavioral context beyond mere action: it discloses the session limit, error code, and advises closing to avoid issues. However, it does not describe return values or error handling, which would make it more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long: one states the action, the other provides rationale. Every sentence adds value, with no redundant words or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter logout tool with no output schema, the description is sufficiently complete: it states the action, gives a rationale (session limits, error code), and suggests when to use it. It could add details about the response format or behavior when no session is open, but these are not critical for understanding the tool's core function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty schema). With no parameters, the baseline is 4, and the description correctly does not include parameter details since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Cierra' (closes) with the resource 'la sesión abierta en el SII' (the open session in the SII), which clearly states the tool's function. It is easily distinguished from sibling tools that list or emit documents, as none handle session management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that SII limits simultaneous sessions and blocks when exceeded (error code), and recommends closing the session when finished ('conviene cerrarla al terminar'). This provides clear context on when to use the tool, though it does not explicitly mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detalle de un DTE emitido específico por tipo y folio en Consultas DTE. Si el documento no es del mes actual, indica fecha_doc en formato YYYY-MM-DD. Requiere certificado digital.
| Name | Required | Description | Default |
|---|---|---|---|
| folio | Yes | Número de folio del documento | |
| tipo_dte | Yes | Tipo DTE: 33=factura, 34=factura exenta, 39=boleta, 61=nota de crédito | |
| fecha_doc | No | Fecha aproximada del documento (YYYY-MM-DD) para buscar en el mes correcto. Por defecto busca en el mes actual. | |
| empresa_rut | No | RUT empresa a consultar. Si se omite, usa SII_EMPRESA_RUT, o se resuelve solo si la persona opera una única empresa. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses a key prerequisite ('Requiere certificado digital') and a conditional behavior (fecha_doc needed for non-current-month documents). However, it omits other behavioral aspects like response format, error conditions, or whether the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: two sentences that immediately state the main purpose, then add the conditional date hint and certificate requirement. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, no output schema), the description is reasonably complete. It covers the core purpose, the required certificate, and a key usage nuance. However, it could be improved by describing what the response contains or clarifying behavior when the document is not found.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all parameters. The description adds a small amount of context for fecha_doc (when to use it), but this largely repeats the schema's explanation. No additional parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Detalle de un DTE emitido específico por tipo y folio' (detail of a specific emitted DTE by type and folio). It uses a specific verb ('detalle') and resource, and distinguishes from sibling list tools and the received DTE getter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use the tool: for a specific DTE by tipo and folio. It also gives a conditional usage hint for fecha_doc when the document is not from the current month, and notes the certificate requirement. However, it doesn't explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detalle de un DTE recibido específico por folio en Consultas DTE. Si el documento no es del mes actual, indica fecha_doc en formato YYYY-MM-DD. Requiere certificado digital.
| Name | Required | Description | Default |
|---|---|---|---|
| folio | Yes | Número de folio del documento | |
| tipo_dte | Yes | Tipo DTE del documento recibido | |
| fecha_doc | No | Fecha aproximada del documento (YYYY-MM-DD) para buscar en el mes correcto. | |
| emisor_rut | Yes | RUT del emisor del documento | |
| empresa_rut | No | RUT empresa a consultar. Si se omite, usa SII_EMPRESA_RUT, o se resuelve solo si la persona opera una única empresa. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It discloses the digital certificate requirement and the conditional behavior for non-current-month documents, adding useful context. However, it does not describe the return format, error behavior, or what 'detalle' encompasses, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core purpose and containing no filler. Every clause contributes value: purpose, a conditional parameter hint, and an important authentication requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a specialized get-tool with no output schema and no annotations, the description covers purpose, authentication, and one parameter behavior. It does not explain return structure, pagination (if any), or edge cases like missing documents. Adequate for simple retrieval but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all 5 parameters with 100% coverage. The description adds meaningful semantics for fecha_doc by specifying when it is needed (if the document is not from the current month), which is not obvious from the schema alone. This elevates it above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves details of a specific received DTE by folio, using the phrase 'Detalle de un DTE recibido específico por folio'. This distinguishes it from sibling tools like sii_dte_list_documentos_recibidos (list) and sii_dte_get_documento_emitido (emitted, not received).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving a specific DTE by folio, but it does not explicitly contrast with alternative tools or state when not to use it. It provides a conditional instruction for including fecha_doc for older documents, which is helpful but not a full alternative/exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista DTEs emitidos por la empresa en Consultas DTE del SII. Requiere certificado digital.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| tipo_dte | No | Tipo DTE: 33=factura, 34=factura exenta, 39=boleta, 61=nota de crédito | |
| empresa_rut | No | RUT empresa a consultar. Si se omite, usa SII_EMPRESA_RUT, o se resuelve solo si la persona opera una única empresa. | |
| fecha_desde | No | Formato YYYY-MM-DD | |
| fecha_hasta | No | Formato YYYY-MM-DD | |
| receptor_rut | No | Filtrar por RUT del receptor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It only discloses the digital certificate requirement. It does not mention that this is a read-only operation, whether a session is needed, any rate limits, or what kind of response to expect. Minimal behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the verb and resource, and includes the key prerequisite. No fluff or repetition; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no annotations, the description is too sparse. It does not explain return values, pagination behavior, or error conditions. For a listing tool with moderate complexity, more context is needed for an agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (83%), so the schema already documents most parameters. The tool description adds no extra semantic details beyond the schema, but the parameter names are mostly self-explanatory. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lista') and resource ('DTEs emitidos por la empresa') within the SII DTE consultation context. This clearly distinguishes it from sibling tools like 'sii_dte_list_documentos_recibidos' or 'sii_dte_get_documento_emitido'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to list issued DTEs, and it mentions a prerequisite (requires digital certificate). However, it offers no explicit comparison to alternatives like 'sii_mipyme_list_dte_emitidos' or 'sii_dte_list_documentos_recibidos', so usage context is mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista DTEs recibidos por la empresa en Consultas DTE del SII. Requiere certificado digital.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| tipo_dte | No | Tipo DTE: 33=factura, 34=factura exenta, 39=boleta, 61=nota de crédito | |
| emisor_rut | No | Filtrar por RUT del emisor | |
| empresa_rut | No | RUT empresa a consultar. Si se omite, usa SII_EMPRESA_RUT, o se resuelve solo si la persona opera una única empresa. | |
| fecha_desde | No | Formato YYYY-MM-DD | |
| fecha_hasta | No | Formato YYYY-MM-DD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only mentions the digital certificate requirement. It does not state whether the operation is read-only, describe return format, pagination, or error handling, which is a significant gap for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded sentences that deliver the core purpose and a prerequisite without unnecessary words. Every phrase earns its place, making it ideal for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 6 optional parameters and no output schema, the description is too brief. It omits details about filtering behavior, return structure, or how the certificate integrates with the parameters, leaving the agent without enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 83% description coverage, so the baseline is 3. The description adds no parameter-specific information beyond what the schema already provides; it only hints at the overall purpose of listing received DTEs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Lista') and resource ('DTEs recibidos por la empresa'), and explicitly names the context ('Consultas DTE del SII'). It distinguishes from the sibling tool for issued documents ('emitidos') through the word 'recibidos'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite ('Requiere certificado digital') but offers no guidance on when to choose this tool over alternatives. It does not mention the sibling tool for issued documents or any selection criteria, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Emite un DTE (factura, nota de crédito, guía de despacho, etc.) en el Sistema de Facturación Gratuito del SII (mipyme.sii.cl). Requiere RUT y DV del receptor separados. Devuelve el folio asignado.
| Name | Required | Description | Default |
|---|---|---|---|
| lineas | Yes | Líneas de detalle del documento | |
| tipo_dte | Yes | Tipo DTE: 33=factura, 34=exenta, 61=N.crédito, 56=N.débito, 52=guía, 46=F.compra | |
| empresa_rut | No | RUT empresa. Si se omite, usa SII_EMPRESA_RUT, o se resuelve solo si la persona opera una única empresa. | |
| receptor_dv | Yes | DV del receptor (ej: "1" o "K") | |
| receptor_rut | Yes | RUT del receptor sin DV (ej: "33333333") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the mutating nature ('Emite') and the return value ('Devuelve el folio asignado'), but does not mention authentication requirements, session prerequisites, or the permanence of the emission. This lacks the depth expected for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb, and every clause serves a purpose. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5-parameter schema covers all inputs and the description mentions the return value, the tool is mostly complete. However, it lacks guidance on authentication state or that the emission is a final submission to SII, which would be helpful in the broader SII tool context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds a useful clarification that RUT and DV are separate, but no other parameter semantics beyond the schema. This aligns with the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Emite' with a resource 'DTE' and clearly names the system (mipyme.sii.cl). It distinguishes from sibling list/get tools by indicating this is the emission tool, and even provides examples of DTE types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states that RUT and DV must be provided separately, giving necessary usage context. However, it does not explicitly mention when to use this tool versus alternatives or provide exclusions, though sibling names make the distinction apparent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista el historial de DTE emitidos en el Sistema de Facturación Gratuito del SII (mipyme.sii.cl). Devuelve folio, tipo, receptor, monto y estado de cada documento.
| Name | Required | Description | Default |
|---|---|---|---|
| folio | No | Filtrar por folio exacto | |
| limit | No | ||
| tipo_dte | No | Filtrar por tipo: 33=factura, 34=exenta, 61=N.crédito, 56=N.débito, 52=guía, 46=F.compra | |
| empresa_rut | No | RUT empresa. Si se omite, usa SII_EMPRESA_RUT, o se resuelve solo si la persona opera una única empresa. | |
| fecha_desde | No | Formato YYYY-MM-DD | |
| fecha_hasta | No | Formato YYYY-MM-DD | |
| receptor_rut | No | Filtrar por RUT del receptor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full transparency burden. It implies a read-only list operation and states the returned fields (folio, tipo, receptor, monto, estado), but it does not disclose requirements like an active session, rate limits, or potential errors beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the main action and resource. It efficiently conveys the system and output without unnecessary detail, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately explains what is returned (folio, tipo, receptor, monto, estado). For a simple list tool with all optional parameters, this covers the essential context, though pagination and session prerequisites are not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (86%), so the schema already documents most parameters. The description adds no additional parameter-level meaning; it only lists the output fields, which does not increase parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the history of issued DTEs in the SII Free Invoicing System (mipyme.sii.cl), using a specific verb ('Lista') and resource ('historial de DTE emitidos'). It also names the system, distinguishing it from sibling tools that operate on other SII subsystems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explicitly naming the system (mipyme.sii.cl) and the scope (issued DTEs), which helps an agent decide when to use it. However, it does not mention alternatives or exclusion criteria, such as when to use sii_dte_list_documentos_emitidos instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista todas las empresas que la persona autenticada puede operar en el Sistema de Facturación Gratuito del SII (mipyme.sii.cl). Usar antes de otras tools cuando SII_EMPRESA_RUT no está configurado.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It correctly frames this as a read-only listing action and mentions the authentication scope ('persona autenticada'). It does not describe return format or pagination, but for a simple no-parameter listing tool the verb 'Lista' sufficiently conveys non-mutating behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficiently written sentence that front-loads the core action and result scope, then adds essential usage timing. Every word contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and a simple list operation, the description fully covers what the tool does, the system and scope, and when to invoke it. It is complete in context, especially as a discovery step before DTE-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty and the description need not explain any parameter semantics. Baseline 4 is appropriate since there is nothing to clarify and no mismatch.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lista') and a clear resource ('empresas que la persona autenticada puede operar'), and identifies the exact system (SII free invoicing, mipyme.sii.cl). This clearly differentiates it from sibling tools that list DTEs or properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use: 'Usar antes de otras tools cuando SII_EMPRESA_RUT no está configurado.' This gives a concrete precondition and implies that when the environment variable is configured, this tool is not needed. It serves as a discovery/prerequisite step without needing to name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista los bienes raíces (propiedades) del RUT persona autenticado en el SII, con comuna, ROL, dirección, destino, datos de inscripción, porcentaje de derechos y avalúo fiscal. Incluye un resumen con total de propiedades, solicitudes, notificaciones, afectación a sobretasa y beneficio de adulto mayor. No requiere SII_EMPRESA_RUT: cuelga de la persona, no de la empresa.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that this is a list operation, describes the scope (person RUT), and details the output contents including a summary. However, it does not mention potential pagination, error conditions, or explicitly state that it is read-only, though 'Lista' implies non-mutating behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core function, and every clause adds value—listing the data fields and then providing a critical note about the authentication scope. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description is quite complete. It explains the data returned, the summary, and the key difference from company-level tools. Minor gaps include lack of return format specifics or error handling, but the provided details are sufficient for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed. It appropriately explains the operation's context and output without needing to clarify parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Lista los bienes raíces (propiedades) del RUT persona autenticado en el SII' with a specific verb and resource. It also differentiates from siblings by emphasizing it operates on the person's RUT rather than an empresa, and lists the exact data fields returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: it is for the authenticated person's real estate properties, and explicitly states 'No requiere SII_EMPRESA_RUT: cuelga de la persona, no de la empresa,' which tells the agent not to supply an empresa context. While it doesn't name an alternative sibling tool, the scope distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0sii_bhe_list_emitidassii_bhe_list_recibidassii_bhe_resumensii_cerrar_sesionsii_dte_get_documento_emitidosii_dte_get_documento_recibidosii_dte_list_documentos_emitidossii_dte_list_documentos_recibidossii_mipyme_emitir_dtesii_mipyme_list_dte_emitidossii_mipyme_list_empresassii_persona_list_bienes_raicesMost tools clearly target distinct resources (properties, mipyme invoices, DTE documents, BHE, session). However, sii_mipyme_list_dte_emitidos and sii_dte_list_documentos_emitidos both list emitted DTEs and could be confused without careful reading; descriptions clarify they are different systems.
All tool names follow a predictable sii_<subdomain>_<action>_<object> pattern, with consistent use of list/get/emit/cerrar verbs. The naming is uniform across all 12 tools.
The 12 tools are well-scoped for the SII domain, covering several distinct areas without excessive granularity. Each tool serves a clear purpose.
The set covers reading properties, listing/emitting DTEs in mipyme, querying DTE via consultas, and BHE summaries, but lacks cancellation/annulment operations, BHE emission, and a get-detail for mipyme DTEs. These gaps limit full workflow coverage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Chile DTE for AI agents - boleta/factura electronica via OpenFactura or LibreDTE. Stateless BYO.
Chilean DTE/SII invoicing — issue invoices, reconcile payments and manage clients with AI agents.
Paraguay SIFEN e-Kuatia: AI agents issue and query electronic invoices, stateless BYO.
Peru CPE invoices for AI agents - issue, query, void facturas/boletas via SUNAT (2 backends).
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/crilam/mcp-sii'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
