Arnés de razonamiento médico, diagnóstico diferencial y RCA clínico para cualquier agente de IA compatible con MCP.
English | 繁體中文
RootCause MCP permite que agentes de propósito general como Claude Code, Codex, Cline, OpenCode, OpenClaw y agentes de Z.ai realicen un flujo de trabajo especializado:
Inventariar y extraer documentos clínicos anonimizados a través del agente anfitrión.
Registrar evidencia fundamentada en la fuente con fragmentos exactos, preservar el tiempo fiel a la fuente y añadir revisiones autorizadas de fuente/anonimización/independencia.
Construir el diferencial basado en mecanismos razonablemente máximo para el fenotipo y el curso temporal, seleccionar explícitamente la hipótesis principal y luego relacionar la evidencia vinculada a la fuente usando razones de verosimilitud directas solo cuando un registro de literatura verificado por separado establezca la calibración cuantitativa.
Tratar las incógnitas como entradas de razonamiento y registrar la justificación de cada candidato, la evidencia de apoyo/refutación/neutral, el discriminador, la certeza cualitativa y el sesgo.
Conectar el razonamiento diagnóstico con Fishbone y 5 Porqués, obtener una disposición HFACS-MES autorizada para cada causa y ejecutar una auditoría conservadora de la obligación de prueba de causalidad.
Producir un informe tipado y legible por máquina con linaje de fuente explícito y resultados de conformidad deterministas.
El agente realiza el razonamiento. El servidor MCP no inspecciona estados ocultos del modelo ni cadenas de pensamiento privadas sin procesar. Proporciona esquemas, restricciones de flujo de trabajo, persistencia, cálculos y registros de auditoría para el razonamiento que el agente elige externalizar explícitamente.
Para la salida orientada al clínico, el renderizador Markdown integrado admite prosa explicativa en chino tradicional mientras preserva los nombres canónicos de diagnóstico, pruebas, fármacos, dispositivos y procedimientos en inglés. Las citas exactas de la fuente, unidades, identificadores, códigos, valores JSON/FHIR y el idioma de plantillas personalizadas nunca se traducen automáticamente.
Este proyecto no es un dispositivo médico y no debe diagnosticar ni tratar pacientes de forma autónoma. El uso clínico requiere revisión humana cualificada, gobernanza local, controles de privacidad y verificación independiente de los documentos fuente.
Related MCP server: SafetyOps MCP Server
El límite determinista del informe final está implementado: las secciones anidadas del
informe están tipadas, cada informe lleva conformance_checks[] legibles por máquina y
la finalización insegura se bloquea por fallos de fuente, DDx, linaje raíz, disposición de
causalidad, revisor o integridad. Las instantáneas finales llevan un revisor, hora con zona
horaria, hash SHA-256 recalculable y rechazan mutación de forma recursiva.
La amplitud del DDx ahora es explícita en lugar de inferirse de un recuento: el Agente
selecciona un marco apropiado al síndrome, revisa cada celda canónica y persiste una
auditoría de amplitud PRIMARIA. REVIEWED_INSUFFICIENT_DATA conserva incógnitas y
discriminadores tipados; NOT_ASSESSED bloquea la finalización. La auditoría establece
cobertura documentada, no corrección clínica.
La conformidad final también lleva el registro completo de revisión de fuente de solo anexión y recalcula su proyección de inventario final, linaje de independencia, selección explícita de diagnóstico principal, enlaces LR calibrados por fuente, semántica temporal fiel a la fuente, revisión HFACS por causa, hechos de guía/preparación, recuentos de brechas y linaje de Porqué/raíz/causalidad. La fecha, el rango, el tiempo relativo y el tiempo desconocido pueden permanecer en un artefacto final válido, pero no pueden ordenarse silenciosamente ni usarse para establecer temporalidad.
La versión 2.0.0a3 (2026-08-19) sigue siendo una alfa de ingeniería, no un MVP
de Agente validado clínicamente. El corpus público de seis casos y el ejecutor son
referencias de ingeniería. Un resultado formal requiere al menos 3 tiempos de ejecución
reales de Agente × 6 casos × 2 repeticiones, paquetes de casos privados externos al
repositorio, oro de retención privado protegido por separado, aislamiento del sistema de
archivos, trazas MCP de tiempo de ejecución/servidor confiables y dos revisores clínicos
cualificados cegados por trabajo con adjudicación de desacuerdos. Esa evaluación está
actualmente en AGENT_EVAL_NOT_ESTABLISHED. Consulte
MVP conformance and evaluation.
Un Agente general puede leer todos los documentos y escribir un informe en un solo prompt largo. Ese enfoque funciona, pero gasta repetidamente contexto en esquemas de herramientas, hechos previos, formato, aritmética de probabilidades, construcción de grafos, comprobaciones de integridad y prosa de informe. RootCause MCP mueve esas operaciones repetibles a código determinista mientras deja el juicio clínico al Agente.
Trabajo | Flujo de trabajo solo con Agente | Asistencia de RootCause MCP |
Contexto de herramientas | Cargar todos los esquemas | Los perfiles |
Resultados de herramientas | Releer texto y JSON duplicados |
|
Enlaces de evidencia cuantitativos | Recalcular y narrar | Aritmética de compatibilidad solo para LR directa calibrada por fuente; de lo contrario, un enlace cualitativo neutral |
Continuidad de casos | Reinyectar conversación anterior | Agregado persistido y rehidratación de reinicio |
Ensamblaje de informes | Reescribir DDx, evidencia, brechas, métricas y grafos | Artefacto Markdown determinista |
Revisión de calidad | Recordar cada elemento de la lista de verificación | Advertencias automáticas de trazabilidad estructural |
Los fixtures de regresión independientes del tokenizador comparan bytes de esquema de
perfil de herramientas, respaldos de texto duplicados y generación de informes determinista.
Use los artefactos CI actuales como fuente de verdad porque los cambios de esquema alteran
esas mediciones. Estos proxies de bytes no son promesas sobre un tokenizador de modelo
específico. El Agente aún debe leer los extractos fuente, generar hipótesis clínicamente
plausibles, elegir relaciones de evidencia defendibles y revisar el artefacto final. Una LR
no neutral requiere un registro de calibración LITERATURE verificado y distinto. Ninguna
prior/posterior no calibrada puede presentarse como probabilidad o certeza clínica; LR=1.0
significa neutral/cuantitativamente desconocido y no cuenta como apoyo o refutación.
Los modelos ligeros o rápidos (como variantes Flash/mini) suelen tener dificultades con casos clínicos complejos: tienden a sacar conclusiones precipitadas, detenerse después de una sola hipótesis (cierre prematuro), descuidar pruebas que desconfirman y omitir reflexiones cognitivas.
RootCause MCP actúa como una Máquina de Estados de Razonamiento activa:
Cada llamada a herramienta central devuelve una carga útil guidance estructurada que evalúa el estado del caso.
Progresión de Etapas: Rastrea automáticamente el progreso a través de EVIDENCE_COLLECTION → DIFFERENTIAL_EXPANSION → BAYESIAN_EVALUATION → COGNITIVE_AUDIT → READY_FOR_SYNTHESIS.
Lista de Verificación de Preparación: Requiere contenido fuente verificado, etiquetas de candidatos tipadas,
al menos tres diagnósticos únicos en dos mecanismos no UNKNOWN, un diagnóstico aplicable
que no debe pasarse por alto, disposición de evidencia/pruebas para cada diagnóstico activo,
apoyo más contradicción o un plan de descarte tipado para diagnósticos principales/que no deben
pasarse por alto, y revisión explícita de incertidumbre/sesgo. Estos son
pisos deterministas de finalización, no un objetivo o límite de amplitud clínica.
Directivas de Próximo Prompt: Proporciona next_recommended_actions explícitas con nombres exactos de herramientas y push_questions socráticas en cada respuesta, lo que permite que los agentes Flash iteran en bucle hasta que el caso esté completo.
Herramientas de Auditoría: Los agentes u orquestadores externos pueden llamar
rc_audit_differential_breadth para persistir la cobertura del marco de cada celda y
rc_audit_reasoning_state para inspeccionar los requisitos previos restantes antes de la generación del informe.
Inspirado en arquitecturas de integración de datos y linaje ETL (como los modelos de verificación de flujo/fuente de Airbyte), RootCause MCP establece una base de evidencia criptográfica determinista sin depender de la memoria probabilística del LLM:
Fragmentos Literales y Anclas de Linaje: Los registros de evidencia capturan citas raw_snippet exactas, rutas de archivo, localizadores de línea y resúmenes SHA-256.
Verificación de Procedencia Determinista: El servicio de dominio ProvenanceVerifier escanea archivos físicos sin procesar en disco (TXT, CSV, HL7, XML) para verificar coincidencias de subcadenas y números de línea sin invocar un LLM.
Detección de Manipulación y Alucinación: Si un agente inventa una cita, hace referencia a una fuente no disponible o presenta una fuente cuyos bytes ya no coinciden con el manifiesto fijado, el servidor mantiene la evidencia sin verificar y devuelve diagnósticos de auditoría.
Revisión de Fuente de Solo Anexión: El manifiesto fijado y el resumen nunca cambian.
La extracción, anonimización y el linaje independiente/derivado avanzan solo a través de
rc_adjudicate_source; cada fuente final necesita un revisor en lista blanca, hora,
motivo e ID de adjudicación estable.
Límite de Arquitectura Limpia: RootCause MCP se centra en contratos de razonamiento y comprobaciones de procedencia; no analiza lotes de PDF, DOCX, imágenes, escaneos, hojas de cálculo o exportaciones de EHR sin procesar.
El agente anfitrión o un extractor aprobado debe producir texto/celdas listos para citar mientras preserva contenido exacto, ubicaciones de fuente, hashes, unidades, negación, precisión temporal, correcciones OCR y método de extracción. Envíe solo hallazgos atómicos estructurados a RootCause MCP y no afirme verificación MCP para fuentes binarias o inaccesibles.
Los protocolos YAML empaquetados y los playbooks de dominio son recursos de DDx retrospectivos versionados y no normativos que el arnés de agente incluido indica a los agentes que lean. Las plantillas Markdown son entradas de renderizado deterministas. Los umbrales de preparación en tiempo de ejecución y las reglas de brechas aún están implementados en Python; editar un protocolo YAML por sí solo no cambia esas puertas. Estos playbooks solo solicitan revisión de mecanismo retrospectivo; no proporcionan manejo de atención activa, instrucciones de tratamiento/rescate ni dosis específicas para el paciente.
SOP Configurable y Playbooks de Dominio (config/protocols/, config/domains/):
anesthesia_mm_rca_protocol.yaml: Marco causal retrospectivo de 4 Niveles (Nivel 0 Ritmo Terminal → Nivel 1 ACLS 5H5T → Nivel 2 Desencadenantes de Tres Flujos [Línea base del paciente vs Insulto quirúrgico vs Farmacología de anestesia] → Nivel 3 Brechas de Sistema Latentes HFACS).
perioperative_shock.yaml y toxicology_sedation.yaml: Prompts de DDx retrospectivos
no normativos para considerar Obstrucción Dinámica del Tracto de Salida del VI (SAM) y
Síndrome de Infusión de Propofol (PRIS), no protocolos de atención activa.
Plantillas Markdown Personalizables (config/templates/):
anesthesia_mm_rca_report_template.md: Formato especializado de revisión de conferencia M&M departamental con llenado de ranuras determinista.
clinical_reasoning_report_template.md: Informe general de razonamiento clínico y acciones de seguridad del paciente.
graph TB
A[General-purpose AI Agent] -->|MCP SDK 2.0| T[8 facade or 25 / 24 / 46 discrete tools]
D[Clinical documents] --> A
subgraph Harness
T --> S[ServerState / case aggregate]
S --> O[ClinicalReasoningOrchestrator]
O --> E[Evidence + provenance + hash]
O --> H[Hypotheses + Bayesian updates]
O --> R[ReasoningChain]
O --> G[Clinical Guidance Engine]
S --> C[ThinkingChain: explicit rationale records]
end
E --> DB[(SQLite / SQLModel)]
H --> DB
R --> DB
C --> DB
S --> CR[CONTRACT report]
CR --> J[JSON]
CR --> F[FHIR-compatible DiagnosticReport]
CR --> M[Deterministic Markdown]
T --> RCA[Fishbone / 5-Why / HFACS-MES / conservative causation audit]
La dirección de dependencias sigue DDD:
Interface -> Application -> Domain <- InfrastructureEl servidor del SDK 2.0 persiste el agregado de razonamiento médico en SQLite:
Evidencia estructurada y metadatos de origen
Hipótesis de diagnóstico diferencial e historial de actualización bayesiana
Registros explícitos de ThinkingStep proporcionados por el agente
Registros de auditoría de ReasoningStep generados por el orquestador
Sesiones de RCA, manifiestos de origen, diagramas de Fishbone y árboles de Why
La autenticación, el cifrado en reposo, el aislamiento de inquilinos, la autorización de roles de revisores, las migraciones de base de datos y los controles de despliegue regulados deben ser proporcionados por el entorno de despliegue antes del uso en producción clínica. Consulte la política de datos PHI y clínicos.
Puede detectar automáticamente uv, sincronizar entornos virtuales, configurar los arneses MCP del cliente (.mcp.json nativo de Copilot, .vscode/mcp.json de VS Code, Claude Desktop y Cline) y ejecutar un diagnóstico stdio de producción con un solo comando:
Windows PowerShell:
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1Linux / macOS / WSL:
chmod +x scripts/setup.sh
./scripts/setup.shEl comando MCP se ejecuta en el host del agente o de la extensión que inicia el servidor. Si VS Code usa WSL, SSH, un Dev Container u otro host remoto, instale
uvy ejecutescripts/setup.shen esa terminal integrada remota. Ejecutarsetup.ps1en Windows local no instalauven el host remoto. Ejecute Developer: Reload Window después de la configuración.
CLI universal de Python:
uv run --locked python scripts/install.py --profile all --target all
uv run --locked python scripts/mcp_doctor.py --config allEjecute los seis escenarios sintéticos incluidos (SAM, PRIS, hiperpotasemia por transfusión, EP postoperatoria, succión de LVAD y diagnóstico tardío). Este script es una regresión/demo para desarrolladores, no un sustituto de las pruebas de aceptación nativas de manifiesto/finalización ni de la validación clínica:
uv run python scripts/run_case_trial.py --case allLa prueba de ejecución en seco del corpus público solo verifica la mecánica del ejecutor/artefactos y
deliberadamente devuelve AGENT_EVAL_NOT_ESTABLISHED:
eval_output="$(mktemp -d)"
uv run python scripts/run_agent_eval.py dry-run \
--output-root "$eval_output" \
--repeats 2Las ejecuciones formales deben usar casos privados externos al repositorio y un estándar de oro privado protegido por separado. Comience con la verificación previa de cierre ante fallos:
uv run python scripts/run_agent_eval.py \
--preflight \
--matrix /secure/adapter-matrix.json \
--corpus-file /secure/private-corpus/corpus.json \
--gold-dir /secure/private-holdout \
--attest-holdout-isolation \
--authorize-provider-egressConsulte el protocolo de evaluación antes de cualquier ejecución formal. La autorización de egreso se aplica solo a entradas sintéticas desidentificadas aprobadas, nunca a registros clínicos reales ni a PHI.
# Install the locked environment
uv sync --locked --all-extras
# Run the MCP SDK 2.0 stdio server
uv run --locked rootcause-mcpLa CLI de Copilot y el Agent Host leen .mcp.json en la raíz del repositorio directamente:
{
"mcpServers": {
"rootcauseMcp": {
"type": "local",
"command": "uv",
"args": ["run", "--locked", "rootcause-mcp"],
"cwd": ".",
"env": {
"ROOTCAUSE_TOOL_PROFILE": "all",
"ROOTCAUSE_RESPONSE_MODE": "compact"
},
"tools": ["*"]
}
}
}El editor de VS Code usa .vscode/mcp.json y lo reenvía al Agent Host activo:
{
"servers": {
"rootcauseMcp": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--locked",
"--directory",
"${workspaceFolder}",
"rootcause-mcp"
],
"cwd": "${workspaceFolder}",
"env": {
"ROOTCAUSE_TOOL_PROFILE": "all",
"ROOTCAUSE_RESPONSE_MODE": "compact"
}
}
}
}Ambos archivos usan intencionalmente la misma clave de servidor rootcauseMcp para que el Agent Host
no cree dos identidades MCP. La configuración compartida usa solo el nombre uv resuelto por PATH. Nunca
confirme C:\...\uv.exe, ROOTCAUSE_DATA_DIR ni ROOTCAUSE_AUTHORIZED_REVIEWERS; proporcione valores
de tiempo de ejecución protegidos en el entorno del host. Coloque servidores MCP no relacionados en la
configuración de usuario o de usuario remoto de VS Code en lugar de confirmar rutas de ejecutables y datos
personales en este repositorio.
spawn ... uv.EXE ENOENTEsto significa que el host de ejecución no puede encontrar el ejecutable configurado. En un host de extensión remota WSL, SSH o contenedor, una causa común es reenviar una ruta absoluta local de Windows. En la terminal remota de VS Code, ejecute:
uv --version
uv sync --locked --all-extras
uv run --locked python scripts/install.py --profile all --target all \
--skip-tests --skip-trial
uv run --locked python scripts/mcp_doctor.py --config allEl doctor debe informar PASS para ambas configuraciones y sus handshakes stdio.
Luego ejecute Developer: Reload Window, reinicie rootcauseMcp desde MCP: List
Servers y use MCP: Reset Cached Tools después de una actualización del catálogo de herramientas. Consulte
la referencia de configuración MCP de VS Code
y la configuración MCP de GitHub Copilot CLI.
Variables de entorno:
Variable | Propósito | Valor predeterminado |
| Base de datos SQLite, puntos de control, reglas aprendidas y exportaciones generadas | Directorio de datos de usuario del SO |
| Anulación de configuración opcional que contiene |
|
| Lista de permitidos separada por separador de ruta del SO para verificaciones exactas de procedencia de texto plano | Directorio de trabajo actual |
| Identidades controladas por el operador separadas por comas autorizadas para verificar, adjudicar fuentes/HFACS o finalizar manualmente | Vacío (revisión manual/aprobación final deshabilitada) |
| Catálogo de herramientas: |
|
|
|
|
Un agente compatible puede usar el flujo de trabajo de herramientas discretas o el flujo de trabajo ultracompacto de 8 fachadas:
rc_start_session(source_manifest={...})
-> rc_add_evidence(temporal={kind=..., raw_value=...})
-> rc_adjudicate_source # each manifest source; authorized append-only review
-> rc_think_aloud / rc_identify_gaps / rc_challenge_assumption
-> rc_propose_hypothesis(planned_tests=[...])
-> rc_audit_differential_breadth(audit={...})
-> rc_link_evidence_to_hypothesis(calibration_status=...,
calibration_source_ref=...)
-> rc_select_leading_hypothesis(reason=..., changed_by=...)
-> rc_get_differential_diagnosis
-> rc_get_reasoning_chain
-> rc_detect_conflicts
-> rc_create_checkpoint
-> rc_init_fishbone / rc_add_cause / rc_confirm_classification
-> rc_ask_why / rc_mark_root_cause
-> rc_verify_causation # conservative audit, not clinical causal proof
-> rc_generate_contract_report(format="markdown", detail_level="standard",
locale="zh-TW", audience="clinician", finalize=false)rc_rca(action="session_start")
-> rc_evidence(action="add")
-> rc_rca(action="session_adjudicate_source")
-> rc_thinking(action="think" / "gap" / "challenge" / "reflect")
-> rc_hypothesis(action="propose" / "audit_breadth" / "link" / "select_leading" / "rank")
-> rc_audit(action="stage_guidance" / "detect_conflicts")
-> rc_checkpoint(action="create")
-> rc_diagram(action="timeline" / "validate")
-> rc_report(action="preview")rc_propose_hypothesis (o rc_hypothesis(action="propose")) registra
mechanism_category, diagnostic_role, reasoning_basis, certainty cualitativa,
justificación clínica, alternativas, incógnitas específicas del candidato y pruebas planificadas
tipadas. Construya el máximo razonable de mecanismos distintos; tres diagnósticos son un
mínimo para la finalización, no el objetivo o el límite del razonamiento. Estos son registros
explícitos creados por el agente, no un volcado del razonamiento oculto del modelo.
Con el renderizador integrado, locale="zh-TW" y audience="clinician" producen
discusión en chino tradicional con nombres médicos canónicos en inglés y una vista ampliada
de evidencia/incógnitas/pruebas a nivel de candidato. Las plantillas personalizadas conservan su
idioma de autoría; los datos JSON y FHIR no se traducen.
Consulte la Guía de integración de agentes para ver ejemplos de cargas útiles.
RootCause MCP aprovecha todo el espectro de primitivas del SDK MCP 2.0 para ofrecer la máxima ergonomía del agente:
Al usar ROOTCAUSE_TOOL_PROFILE=condensed, la superficie anunciada se consolida
en 8 herramientas fachada polimórficas, lo que reduce la sobrecarga de descubrimiento/esquema. Algunas
operaciones administrativas permanecen solo discretas; el arnés incluido enumera la asignación
exacta y entrega la misma sesión a un perfil apropiado en lugar de omitirlas silenciosamente:
rc_evidence: Agregar, obtener o verificar procedencia física.
rc_hypothesis: Proponer candidatos, auditar la amplitud del marco, vincular evidencia, seleccionar explícitamente el líder, inspeccionar o excluir.
rc_thinking: Registrar justificación clínica, reflexionar sobre sesgos cognitivos, identificar brechas o desafiar suposiciones.
rc_audit: Consultar orientación de múltiples bucles, auditar la integridad del razonamiento o detectar contradicciones/omisiones.
rc_report: Generar informes de contrato deterministas o exportar artefactos de auditoría.
rc_diagram: Renderizar líneas de tiempo de eventos cronológicos, auditar sintaxis de Mermaid o exportar gráficos.
rc_checkpoint: Crear, listar o restaurar instantáneas de estado de caso con verificación de integridad.
rc_rca: Enrutar la revisión de sesión/origen más los flujos de trabajo tradicionales de Fishbone (6M), 5-Why y HFACS-MES.
Inspeccione el conocimiento del dominio y los estados de caso con 0 sobrecarga de llamadas de herramienta:
URIs de protocolo y plantilla estáticos (19 recursos en la instantánea 2.0.0a3):
clinical://contracts/case-input-manifest: esquema canónico de traspaso de múltiples fuentes.
clinical://contracts/case-analysis-report: esquema canónico de salida estandarizada.
clinical://protocols/anesthesia-mm-rca-protocol: SOP de razonamiento causal hacia atrás de 4 niveles.
clinical://protocols/clinical-reasoning-sop: manual de investigación diagnóstica central.
clinical://protocols/non-death-adverse-event-protocol: protocolo de análisis de barreras para cuasi accidentes y eventos adversos.
clinical://protocols/timeline-patterns: definiciones de patrones temporales fieles a la fuente.
clinical://templates/anesthesia-mm-rca-report-template: plantilla de informe en Markdown.
clinical://templates/clinical-reasoning-report-template: plantilla general de informe de razonamiento clínico.
clinical://templates/clinician-ddx-discussion-zh-tw: plantilla de discusión de DDx en chino tradicional orientada al clínico.
clinical://templates/near-miss-adverse-event-rca-template: plantilla de queso suizo y fallo de barrera.
clinical://domains/*: 9 manuales de DDx retrospectivos no normativos:
anaphylaxis-crisis, anesthesia-perioperative-arrest,
delayed-diagnosis-systems, difficult-airway-crisis,
local-anesthetic-toxicity, lvad-mechanical-crisis, pediatric-opioid,
perioperative-shock y toxicology-sedation.
Plantillas de recursos de caso dinámicos (4 en la instantánea 2.0.0a3):
clinical://sessions/{session_id}/report: informe de caso renderizado actual.
clinical://sessions/{session_id}/timeline: línea de tiempo de eventos cronológicos actual.
clinical://sessions/{session_id}/guidance: etapa de razonamiento en vivo, lista de verificación y preguntas socráticas de empuje.
clinical://sessions/{session_id}/conflicts: auditoría en vivo de contradicciones, paradojas y omisiones.
Inicie flujos de trabajo de investigación clínica estandarizados con un clic en Claude Desktop, VS Code o Cline:
anesthesia_mm_investigation: investigación de M&M de anestesia hacia atrás de 4 niveles.
perioperative_crisis_differential: expansión del diferencial de crisis con triaje 5H5T.
near_miss_barrier_analysis: RCA de barrera de eventos adversos no mortales con queso suizo.
delayed_diagnosis_investigation: investigación de trayectoria diagnóstica y sesgo cognitivo.
clinician_ddx_discussion_zh_tw: discusión general de DDx en chino tradicional orientada al clínico
con máxima amplitud razonable de mecanismos, incógnitas explícitas, evidencia de apoyo/refutación/neutral
vinculada a fuentes, pruebas discriminantes y certeza cualitativa.
El servidor proporciona automáticamente meta-instrucciones a nivel de sistema durante el handshake de MCP, anclando a los agentes de IA a un rigoroso fundamento de fuentes, razonamiento causal hacia atrás de 4 niveles, prueba de hipótesis de refutación y transparencia sobre sesgos cognitivos.
Categoría | Conteo | Propósito |
Transparencia cognitiva | 5 | Razonamiento explícito, reflexión, brechas, supuestos, recuperación de cadena de pensamiento |
Evidencia y procedencia | 3 | Agregar, recuperar y verificar evidencia estructurada con fragmentos sin procesar y hash SHA-256 |
Diagnóstico diferencial | 6 | Proponer, auditar la amplitud del marco, vincular evidencia, seleccionar explícitamente la principal, inspeccionar y excluir hipótesis |
Cadena de razonamiento y orientación | 3 | Recuperar la cadena de acciones de auditoría, exportar diagramas y auditar la finalización del razonamiento |
Análisis de brechas y detección de conflictos | 1 | Detectar contradicciones diagnósticas, respuestas paradójicas a medicamentos y omisiones de monitoreo |
Puntos de control de casos | 3 | Crear, restaurar y listar instantáneas de casos JSON con verificación de integridad |
Informe CONTRACT | 1 | Generar salida JSON preliminar o final controlada, compatible con FHIR, o Markdown determinista |
Taxonomía HFACS-MES | 6 | Sugerir, confirmar, inspeccionar, aprender, recargar y mapear clasificaciones |
Gestión de sesiones | 5 | Iniciar, agregar adjudicaciones de revisión de fuentes, recuperar, listar y archivar sesiones de RCA con persistencia SQLite |
Espina de pescado (Ishikawa 6M) | 4 | Inicializar, agregar causas, inspeccionar y exportar |
Árbol de por qué (análisis de 5 porqués) | 6 | Preguntar por qué, inspeccionar, vincular cruzadamente, marcar causas raíz, exportar y enseñar (persistido en SQLite) |
Verificación y diagramas | 3 | Auditoría de causalidad conservadora, auditor de sintaxis Mermaid y renderizador de línea de tiempo |
Total (discreto) | 46 | Expone 46 herramientas discretas en |
Artefacto | Salida legible por máquina | Salida de diagrama |
Espina de pescado | JSON | Diseño Mermaid 6M Ishikawa con espina, causas y subcausas |
Árbol de por qué | JSON | Jerarquía Mermaid con causas raíz y enlaces causales cruzados |
Cadena de razonamiento | JSON | Rastro de auditoría ordenado Mermaid con referencias de evidencia/hipótesis |
Gráfico de evidencia | CONTRACT JSON | Gráfico Mermaid integrado de soporte/contradicción |
Línea de tiempo de eventos | JSON | Mermaid |
uv run pytest -W error::ResourceWarning
uv run ruff check .
uv run ruff format --check .
uv run mypy src --ignore-missing-imports
uv run bandit -c pyproject.toml -r src --severity-level low --confidence-level medium
uv run vulture src tests --min-confidence 80
uv export --frozen --no-dev --no-emit-project --no-hashes --quiet --output-file requirements-audit.txt
uvx --from "pip-audit==2.9.0" pip-audit --strict --requirement requirements-audit.txt
uv build
uvx --from "twine==6.2.0" twine check dist/*Use la ejecución de CI actual y los artefactos de lanzamiento como fuente de verdad para los conteos de pruebas, cobertura, hallazgos de seguridad y resultados de empaquetado. Estas puertas de ingeniería validan el comportamiento del software; no establecen el rendimiento clínico del agente ni la validez clínica.
src/rootcause_mcp/
├── domain/ # Entities, value objects, repository contracts, services
├── application/ # Case aggregate, orchestration, progress guidance
├── infrastructure/ # SQLModel repositories and safe export paths
├── interface/ # MCP tool schemas and handlers
└── server_v2.py # Sole MCP SDK 2.0 entry pointEl diseño hace referencia a trabajos disponibles públicamente sobre razonamiento clínico, RCA, FHIR, procedencia, inferencia causal y evaluación de agentes. La encuesta de investigación con fecha establece el límite del producto; los informes por repositorio registran qué se puede aprender, cómo se debe integrar y citar un paquete base, y qué restricciones de licencia o uso de datos prohíben la reutilización directa.
Apache License 2.0. Ver LICENSE.
Add a directed or bidirectional causal relationship between Why nodes. Use this to capture escalation loops, feedback cycles, or mitigation links that are not visible in a simple linear 5-Why chain.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| source_node_id | Yes | The source WhyNode ID | |
| target_node_id | Yes | The target WhyNode ID | |
| relationship | No | Type of causal relationship | feedback |
| strength | No | Relationship strength (0.0-1.0) | |
| bidirectional | No | Whether the influence also goes from target back to source | |
| note | No | Optional explanatory note for this link | |
| evidence | No | Optional evidence supporting the link |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'adds a relationship' without disclosing mutation effects, prerequisites, or error states. Does not explain behavior on duplicate links or required permissions.
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?
Two concise sentences: first defines action, second provides context. 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?
With 8 parameters and no output schema, the description lacks guidance on parameter selection (e.g., when to use each relationship type) and does not mention return value or validation outcomes.
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 coverage is 100% with detailed parameter descriptions. The description adds no extra meaning beyond 'directed or bidirectional' which maps to the bidirectional field. Baseline 3 applies.
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?
Clearly states verb 'Add' and resource 'causal relationship between Why nodes'. Distinguishes from linear 5-Why chain, providing specific use cases (escalation loops, feedback cycles, mitigation links).
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?
Explicitly states when to use (non-linear relationships). Implicitly differentiates from rc_add_cause but lacks explicit 'when not to use' or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a cause to a Fishbone category. Each cause can have sub-causes, evidence, and HFACS classification.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| category | Yes | The 6M category for this cause | |
| description | Yes | Description of the cause | |
| sub_causes | No | List of sub-causes (optional) | |
| hfacs_code | No | HFACS classification code (optional) | |
| evidence | No | Supporting evidence (optional) |
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 fails to disclose side effects (e.g., whether it modifies the session state), return behavior, error conditions, or dependencies. The description only repeats information already available in the parameter schema without adding behavioral context.
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, efficient sentence that front-loads the primary action. It is not verbose, and every word serves a purpose. However, it could benefit from a brief structured layout for clarity, such as separating the primary action from optional details.
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 6 parameters, no output schema, and no annotations, the description is too sparse. It omits crucial context such as the need for a prior session, error handling, and the meaning of HFACS classification. A more complete description would explain typical usage and expected outcomes.
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%, granting a baseline of 3. The description adds minimal meaning beyond the schema: it mentions sub-causes, evidence, and HFACS classification, which are already defined as optional parameters. No constraints or relationships between parameters are explained.
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 verb 'Add' and the resource 'cause to a Fishbone category', distinguishing it from siblings like rc_add_causal_link or rc_init_fishbone. It also lists optional attributes (sub-causes, evidence, HFACS classification), making the tool's function precise and 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 does not specify when to use this tool versus alternatives (e.g., rc_add_causal_link). No context about prerequisite actions (like initializing a session or fishbone) or typical workflow is provided, leaving the AI agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a completed RCA session. Archived sessions are preserved but marked as inactive.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID to archive |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions that archived sessions are preserved but marked inactive, but does not disclose potential side effects, reversibility, permissions required, or impacts on related data.
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 succinct sentence that front-loads the key information. Every word contributes meaning, and there is no unnecessary detail.
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 tool with one parameter and no output schema, the description is minimally adequate. However, it lacks details about the behavior of archiving (e.g., whether it can be undone, impact on list views, or related links).
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 coverage is 100% for the single parameter 'session_id', and the description adds no additional meaning beyond the schema. The baseline score of 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 that the tool archives a completed RCA session, specifying the resource (RCA session) and action (archive). However, it does not differentiate from sibling tools, but since no other archive tool exists, this is acceptable.
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 only implies that the session should be completed before archiving, but does not provide explicit guidance on when to use this tool vs alternatives, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask 'Why?' to drill down into root causes using 5-Why analysis. Creates or extends a WhyChain for the session. Each call goes one level deeper (up to 5 levels). This is the CORE tool for systematic root cause reasoning.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| answer | Yes | The answer to 'Why?'. This becomes the basis for the next question. Example: 'Because the nurse miscalculated the dose' | |
| parent_node_id | No | Optional: ID of parent node to branch from. If not provided, continues from the last node or creates first Why. | |
| evidence | No | Supporting evidence for this answer (optional) | |
| initial_problem | No | The initial problem statement. Required only for the FIRST Why in a chain. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the full burden. It discloses the key behavioral aspect: each call goes one level deeper up to 5 levels. It does not describe the output format or what happens after the 5th level, but overall it is fairly 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 three sentences, each earning its place: first states purpose, second explains behavior with constraints, third emphasizes importance. No fluff.
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 output schema and no annotations, the description should hint at the return value. It does not describe what the tool returns after each call. It covers the reasoning flow well but omits output expectations, making it slightly incomplete.
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 coverage is 100%, so the schema already documents each parameter. The description adds value by explaining the role of 'initial_problem' (required only for first Why) and the default behavior of 'parent_node_id', which clarifies usage 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 action ('Ask Why?'), the resource ('drill down into root causes using 5-Why analysis'), and distinguishes from siblings by labelling itself 'the CORE tool for systematic root cause reasoning.'
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 each call goes one level deeper (up to 5 levels) and that it creates or extends a WhyChain, giving clear context for when to use it. However, it does not explicitly mention when not to use it or compare to alternative tools like rc_add_cause or rc_get_why_tree.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transform a completed Why Tree into a teaching-ready lesson plan. Generates learning objectives, common pitfalls, discussion prompts, and reverse-causality questions for medical learners.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| learner_level | No | Target learner level | medical_student |
| format | No | Output format | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It describes outputs but does not disclose side effects (e.g., whether the tool modifies the session), required permissions, or any limitations. The behavior is not fully 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?
Two sentences with no wasted words. The main purpose is front-loaded, and every sentence adds value by listing outputs.
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 3 parameters with 100% schema coverage and no output schema, the description adequately explains the tool's function and outputs. However, it could be more specific about the output format (though format param exists) and does not state dependencies like authentication or session validity.
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 coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema; the parameters are straightforward, and the description focuses on outputs rather than parameter semantics.
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 specifies the verb 'Transform' and the resource 'completed Why Tree into a teaching-ready lesson plan', and lists the generated outputs (learning objectives, pitfalls, etc.). It clearly distinguishes from sibling tools like export functions.
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 the tool should be used when a Why Tree is completed, but does not explicitly state when to use it versus alternatives like rc_export_why_tree, nor does it provide exclusions or prerequisites beyond the tree being complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm an HFACS classification as correct. This helps the system learn from expert decisions and improve future suggestions. Confirmed classifications are stored as learned rules.
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | The original cause description | |
| hfacs_code | Yes | The confirmed HFACS code (e.g., 'UA-S', 'PC-C-PMC', 'EF-RE') | |
| reason | Yes | Brief explanation of why this classification is correct | |
| session_id | No | Optional session ID for tracking | |
| confidence | No | Confidence level (0.0-1.0) |
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 discloses that confirmed classifications are stored as learned rules, which is a key behavioral trait (side effect). This helps the agent understand the learning impact. It could mention irreversibility or permission requirements, but the disclosure is adequate.
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 consists of two concise, front-loaded sentences with no wasted words. Every sentence adds value: action statement, learning purpose, and storage behavior.
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 lack of output schema, the description does not explain the return value, but the action is simple. It covers the core purpose and key behavior. It could mention that the tool requires a prior suggestion or that the reason parameter is used for traceability, but it is sufficiently complete for a straightforward confirmation 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?
Schema coverage is 100%, so each parameter already has a description. The tool description adds no additional meaning beyond what the schema provides, earning the baseline score of 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 the action 'Confirm an HFACS classification as correct' and specifies the resource. It explains the higher-level purpose: helping the system learn and improving future suggestions, distinguishing it from sibling tools like rc_suggest_hfacs and rc_list_learned_rules.
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 implicitly indicates that this tool should be used when a classification needs to be confirmed and stored as a learned rule. It provides context for learning but does not explicitly state when not to use it or mention alternatives. However, given sibling tools, the usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export Fishbone diagram in various formats. Supports Mermaid, JSON, and Markdown formats.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| format | No | Export format | mermaid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description only hints at non-destructive behavior (export) but does not disclose details like whether the session must be active, potential side effects, or error conditions.
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 concise with two short sentences, no unnecessary details, and front-loaded with the core purpose.
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 two-parameter tool with no output schema, the description is adequate but incomplete: it does not specify the output format or behavior on errors, which would be helpful.
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 coverage is 100% with descriptions for both parameters. The description adds context by listing the supported formats, which matches the enum, but does not provide additional 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 exports a Fishbone diagram in specific formats (Mermaid, JSON, Markdown), which distinguishes it from sibling tools like rc_get_fishbone (retrieves data) and rc_export_why_tree (exports a different diagram type).
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?
No guidance is provided on when to use this tool versus alternatives like rc_get_fishbone or rc_export_why_tree. The description lacks context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export Why Tree in various formats. Supports Mermaid (flowchart), JSON, and Markdown.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| format | No | Export format | mermaid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavior. It states 'Export' but does not specify if the operation is synchronous, generates a file, returns a string, or has any side effects. The behavioral details are minimal.
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?
Two concise sentences covering the essential action and supported formats. No unnecessary words or repetition.
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?
Lacks critical info about the output: does the tool return a downloadable file, a string, or something else? Without an output schema, the description should clarify the nature of the export result.
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 coverage is 100% and clearly describes both parameters. The description simply echoes the format options, adding no new semantic depth beyond what the enum already provides.
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 exports a 'Why Tree' and lists the supported formats (Mermaid, JSON, Markdown). It distinguishes from sibling tools like rc_get_why_tree (retrieval) and rc_export_fishbone (different diagram type).
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 purpose is clear but no explicit guidance on when to use this tool versus alternatives like rc_get_why_tree for retrieval or other export tools. Usage is implied but without conditional or exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get mapping between 6M Fishbone categories and HFACS codes. Shows how Fishbone categories (Personnel, Equipment, Material, Process, Environment, Monitoring) correspond to HFACS levels. Useful for cross-framework analysis and ensuring comprehensive coverage. Also provides Why Tree depth guidance for each category.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Optional: specific 6M category to retrieve mapping for. If not specified, returns all mappings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States it provides mapping and Why Tree depth guidance, but lacks details on permission requirements, rate limits, or response format. Adds value beyond schema but not extensive.
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?
Three sentences, front-loaded with action, no wasted words. Efficiently covers purpose, details, and context.
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?
Without output schema, description adequately explains the type of information returned (mapping and depth guidance). Given low complexity, it is sufficiently complete, though could elaborate on the output structure.
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 coverage is 100% with parameter description already explaining the default behavior. Description does not add new information about parameter beyond what schema provides, so 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?
Description clearly states the tool retrieves mappings between 6M Fishbone categories and HFACS codes, lists all six categories, and explains it shows correspondence. This distinguishes it from sibling tools like rc_get_fishbone or rc_get_hfacs_framework.
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?
Indicates use for cross-framework analysis and comprehensive coverage, giving clear context. Does not explicitly state when not to use or compare to siblings, but the purpose is sufficiently clear for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete Fishbone diagram for a session. Returns all categories and causes in structured format.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description only indicates it returns the diagram. It does not disclose whether the operation is read-only, behavior on invalid session IDs, or any side effects. The 'get' prefix implies idempotency but is not explicitly stated.
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?
Two sentences efficiently convey purpose and output. Every word is necessary with 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?
For a simple getter with one parameter and no output schema, the description is minimally adequate. It lacks details on output structure, error handling, and how it differs from similar retrieval tools among 20+ siblings.
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?
There is one parameter (session_id) with 100% schema coverage. The description adds no additional meaning beyond the schema's 'The session ID' – no format, examples, or constraints. Baseline 3 applies.
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 retrieves the complete Fishbone diagram for a session, returning all categories and causes in a structured format. It uses specific verbs and resource naming, and implicitly distinguishes from export or other retrieval tools like rc_get_why_tree.
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?
No guidance on when to use this tool versus alternatives such as rc_get_session or rc_get_why_tree. The description does not provide any exclusions, prerequisites, or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get HFACS-MES framework structure and category definitions. Use this to understand the classification hierarchy and criteria.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Optional: specific level to retrieve (EF, OI, US, PC, UA). If not specified, returns all levels. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description implies a read operation but does not explicitly state read-only nature, response details, or any constraints beyond parameter 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?
Two short sentences, front-loaded with purpose, no extraneous 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 retrieval tool with one optional parameter and no output schema, the description fully covers purpose and parameter semantics.
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 coverage is 100%, baseline 3. Description adds clarity by noting the default behavior when not specified ('returns all levels'), which goes beyond 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?
Description clearly states the tool retrieves the HFACS-MES framework structure and category definitions, with a specific verb ('Get') and resource. It distinguishes from sibling tools that add causes or links.
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?
Description suggests using it to understand classification hierarchy but does not explicitly state when to use vs alternatives or 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.
Get details of an RCA session by ID. Returns session status, current stage, and progress.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns session status, stage, and progress, but does not disclose whether it is read-only, idempotent, or any potential side effects. Basic behavioral context is present, but not comprehensive.
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 that efficiently conveys the purpose and output. It is front-loaded with the action and resource, with no redundant or extraneous 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?
For a simple retrieval tool with one parameter, the description adequately covers what it does and what it returns. It does not address error handling or edge cases, but given the low complexity, 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?
Schema coverage is 100% with a single parameter 'session_id' described as 'The session ID to retrieve'. The description adds no additional meaning, constraints, or examples beyond the schema. 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 the tool retrieves session details by ID and specifies the returned data (status, stage, progress). It distinguishes itself from sibling tools like rc_list_sessions (which lists sessions) and rc_start_session (which creates).
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 does not explicitly state when to use this tool versus alternatives (e.g., after obtaining a session ID from rc_list_sessions). It lacks guidance on prerequisites, exclusions, or context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete Why Tree (5-Why analysis chain) for a session. Shows all Why questions and answers in hierarchical format.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It describes a read operation (get, shows) and implies no side effects, but does not explicitly state it is non-destructive or discuss permissions. This is acceptable for a simple retrieval but not fully 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?
Two concise sentences that front-load the core action and output. Every sentence adds value with no redundancy or extraneous 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?
Given the single parameter, no output schema, and low complexity, the description sufficiently explains what the tool returns. The sibling list adds context, but the description alone is adequate for a simple retrieval 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 parameter 'session_id' is already described in the schema with full coverage. The description adds no further meaning about the parameter format or constraints beyond what the schema provides, meeting the baseline.
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 gets the complete Why Tree for a session, specifying the format (5-Why analysis chain, hierarchical). This differentiates it from sibling tools like rc_get_fishbone or rc_export_why_tree.
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?
No explicit guidance on when to use this tool versus alternatives like rc_get_fishbone or rc_get_hfacs_framework. The context implies it is for viewing the Why Tree but lacks exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialize a Fishbone (Ishikawa) diagram for a session. Creates a 6M structure (Personnel, Equipment, Material, Process, Environment, Monitoring) with the problem statement as the fish head.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID to create fishbone for | |
| problem_statement | Yes | The problem statement (fish head) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose behavioral traits such as idempotency, side effects on existing fishbone for the same session, or required permissions. For a mutation tool, this is a significant gap.
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?
Two sentences that front-load the core purpose and key structural detail (6M categories). No redundant words. Efficient and clear.
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?
Covers the main action and structure created. For a parameter-light, no-output-schema tool, it is mostly complete. However, could mention what happens if a fishbone already exists for the session (overwrite vs error) and return behavior.
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 coverage is 100% and both parameters have descriptions (session_id and problem_statement) that explain their roles. The tool description adds context about the 6M structure but does not enhance parameter-level 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?
Clearly states the verb 'Initialize' and describes creating a Fishbone diagram with a 6M structure and problem statement as fish head. Distinguishes from siblings like rc_get_fishbone (retrieval) and rc_add_cause (modification).
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?
Implied usage (for starting a new fishbone diagram) but no explicit guidance on when to use vs siblings like rc_start_session or rc_get_fishbone. Lacks 'when not to use' or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all learned classification rules. Shows rules that have been confirmed by experts.
| Name | Required | Description | Default |
|---|---|---|---|
| hfacs_code | No | Optional: filter by specific HFACS code | |
| min_confidence | No | Minimum confidence threshold |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that only rules confirmed by experts are returned, which is a key behavioral trait. However, with no annotations, it lacks details on authorization, pagination, or complete behavior. The description adds value beyond annotations but is not thorough.
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 very concise with two short sentences, front-loading the purpose. Every word earns its place, though a bit more structure (e.g., bullet points) could improve scannability.
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 output schema and two simple filters, the description is adequate but could mention return format, sorting, or pagination. It provides enough context for a basic list tool but lacks completeness for complex scenarios.
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% (both parameters have descriptions in the schema). The tool description does not add any additional meaning beyond what the schema already provides, so it meets the baseline of 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 uses the specific verb 'List' and identifies the resource as 'learned classification rules', adding that these are confirmed by experts. This clearly distinguishes it from sibling tools like rc_reload_rules or rc_suggest_hfacs.
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 for viewing confirmed rules but provides no explicit guidance on when to use this tool versus alternatives such as rc_get_hfacs_framework or rc_get_session. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all RCA sessions with optional filters. Returns summary of all sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by session status | |
| case_type | No | Filter by case type | |
| limit | No | Maximum number of sessions to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Returns summary of all sessions'. It does not disclose behavioral traits such as side effects, authentication needs, or rate limits. For a read-only list tool, this is minimal.
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 with two front-loaded sentences. Every word is necessary and adds value without 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 low complexity of a list tool with optional filters, the description adequately covers the purpose and return type. However, with no output schema, it could briefly mention that it returns a summary (not full details), which it does. Nearly 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?
Schema coverage is 100% with clear parameter descriptions in the input schema. The description only adds 'with optional filters' which adds no extra meaning beyond the schema, 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 'List all RCA sessions with optional filters', providing a specific verb (list) and resource (RCA sessions). It distinguishes itself from siblings like rc_get_session by implying a list versus a single session.
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 for listing sessions but does not explicitly state when to use it versus alternatives or provide any exclusion criteria. No guidance on 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.
Mark a WhyNode as the identified root cause. This indicates the analysis has reached a fundamental cause that requires action.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| node_id | Yes | The WhyNode ID to mark as root cause | |
| confidence | No | Confidence level (0.0-1.0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only says it 'indicates the analysis has reached a fundamental cause that requires action', but does not disclose what changes occur, e.g., if the node is locked, if effects are reversible, or if confirmation is needed.
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?
Two sentences, front-loaded with the action, no extraneous words. Every sentence 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?
Given 3 parameters, no output schema, and no annotations, the description is minimally adequate but lacks behavioral and usage context that would fully inform an agent.
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 coverage is 100%, so baseline is 3. The description does not add any meaning beyond the schema—it doesn't explain the confidence parameter or how to choose the node_id.
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 verb 'Mark' and the resource 'WhyNode as the identified root cause', and distinguishes this from sibling tools like rc_add_cause or rc_confirm_classification by specifying the action of marking the root cause.
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 no guidance on when to use this tool vs alternatives, such as rc_confirm_classification or rc_add_cause. It does not specify prerequisites or situations where marking a root cause is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reload classification rules from YAML files. Use this after manually editing config files.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavior. It states the action (reload from YAML) but does not mention potential side effects (e.g., overwriting existing rules, validation errors). The description is adequate but lacks depth about what happens during reload.
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 consists of two concise sentences with no unnecessary words. It is front-loaded with the core purpose and provides usage context, making it highly efficient.
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 tool with no parameters and no output schema, the description covers the essential purpose and usage. It could mention potential outcomes (e.g., success messages, error handling) but is still reasonably complete for the task.
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 zero parameters and 100% coverage (since none exist). The description does not need to add parameter information. Following the baseline rule for zero parameters, a score of 4 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 the action ('Reload') and the resource ('classification rules from YAML files'), distinguishing it from sibling tools that add, confirm, or export classifications. It uses a specific verb and resource, 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 explicitly states when to use the tool: 'after manually editing config files.' This provides clear context for usage, though it does not mention when not to use it or list alternatives. The guidance is sufficient for this simple action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new RCA analysis session. Creates a new session with the specified case type and title. Returns session_id for subsequent operations.
| Name | Required | Description | Default |
|---|---|---|---|
| case_type | Yes | Type of case being analyzed | |
| case_title | Yes | Brief title for the case | |
| initial_description | No | Initial description of the incident |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose side effects and behaviors. It only states 'creates a new session' without mentioning auth requirements, potential conflicts, or whether the session is persisted. Minimal transparency for a creation 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?
Two sentences, no wasted words. Could be slightly improved with structured format (e.g., listing return value separately), but overall concise and clear.
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?
Explains return value despite no output schema, but missing details on error cases, validation rules for case_type enum, and what happens if required fields are missing. Adequate but not complete for a tool with 3 parameters.
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 coverage is 100%, so baseline is 3. The description adds value by mentioning return of session_id, but does not elaborate on parameter meaning beyond schema definitions.
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?
Description clearly states it starts a new RCA analysis session with specified case type and title, and returns session_id. This is specific and distinguishes from sibling tools like rc_list_sessions or rc_get_session.
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?
Implied usage as the initial step for RCA analysis, but no explicit guidance on when to use versus alternatives like rc_list_sessions or rc_archive_session. No exclusion criteria provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest HFACS-MES classification codes for a cause description. Returns ranked suggestions with confidence scores. HFACS-MES has 5 levels: External Factors, Organizational Influences, Unsafe Supervision, Preconditions, Unsafe Acts.
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | The cause description text to classify | |
| domain | No | Optional domain context for better suggestions (e.g., 'anesthesia', 'surgery', 'nursing') | |
| max_suggestions | No | Maximum number of suggestions to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry full burden. It states the tool returns ranked suggestions with confidence scores and lists HFACS-MES levels, but lacks details on side effects, permissions, or output specifics like the format of suggestions.
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 at two sentences, front-loading the purpose. It efficiently conveys the key function and context, though it could incorporate usage guidelines without adding much length.
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 provides high-level output info (ranked suggestions with confidence scores) and lists HFACS-MES levels. However, it does not explain confidence scoring or return structure, leaving some gaps in completeness.
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?
All three parameters have descriptions in the input schema (100% coverage). The tool description does not add extra meaning beyond the schema, so baseline score of 3 applies.
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?
Clearly states the tool suggests HFACS-MES classification codes for a cause description and returns ranked suggestions with confidence scores. The description differentiates from sibling tools which involve adding causes, links, sessions, etc.
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?
No explicit guidance on when to use this tool versus alternatives like rc_confirm_classification or rc_get_hfacs_framework. The description does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify causal relationship between cause and effect using the Counterfactual Testing Framework. Tests: 1) Temporality - Did cause precede effect? 2) Necessity - Would effect occur without cause? 3) Mechanism - Is there a plausible causal pathway? 4) Sufficiency - Is cause alone sufficient for effect?
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session ID | |
| cause | Yes | The cause event | |
| effect | Yes | The effect event | |
| verification_level | No | 'standard' tests Temporality+Necessity. 'comprehensive' tests all 4 criteria. | standard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are given, so the description carries full burden. It details the four tests but omits behavioral traits like side effects, idempotency, required permissions, or what happens on invalid input. It partially compensates with internal logic but lacks safety/state context.
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 purpose, and uses a clear list format. Every sentence is informative. Loses a point for lacking structured formatting (e.g., line breaks for the list) but overall efficient.
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?
No output schema is provided, and the description does not explain what the tool returns (e.g., boolean, scores). It also does not describe how session_id is used or caveats about nested objects. Lacks completeness for an agent to invoke correctly.
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 coverage is 100%, so baseline is 3. The description lists the four tests but does not explicitly link them to parameters. The verification_level parameter is already well-described in the schema. The description adds marginal value beyond 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 verb 'Verify' and the resource 'causal relationship', and lists four specific tests. This distinguishes it from sibling tools like rc_add_causal_link or rc_confirm_classification.
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?
No explicit guidance on when to use this tool vs alternatives. Sibling tools exist but no differentiation criteria are provided. The tests imply a verification scenario, but 'when-not' and alternatives are missing.
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.0rc_add_causal_linkrc_add_causerc_archive_sessionrc_ask_whyrc_build_teaching_caserc_confirm_classificationrc_export_fishbonerc_export_why_treerc_get_6m_hfacs_mappingrc_get_fishbonerc_get_hfacs_frameworkrc_get_sessionrc_get_why_treerc_init_fishbonerc_list_learned_rulesrc_list_sessionsrc_mark_root_causerc_reload_rulesrc_start_sessionrc_suggest_hfacsrc_verify_causationEach tool targets a distinct aspect of RCA (session management, Fishbone, Why Tree, HFACS, verification, teaching cases). No two tools serve the same purpose, and descriptions clearly differentiate them.
All tools follow the rc_verb_noun pattern consistently using snake_case. Verbs like start, get, list, add, ask, export, etc., are predictable and logically applied.
21 tools cover a rich domain comprehensively. While slightly above the ideal range, each tool has a clear role and no redundancy, making the count reasonable for this complex subject.
Covers creation, retrieval, and updates well, but lacks deletion or removal operations for causes, links, or classifications. This can hinder correction of mistakes, leaving notable gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Physician-reviewed medical opinions and prescriptions for AI agents.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
Medical RAG: semantic search for clinical guidelines, drug interactions, diagnoses & EHR data.
Medical RAG: semantic search for clinical guidelines, drug interactions, diagnoses & EHR data.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/u9401066/rootcause-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server