Integrates with NVIDIA NIM (Nemotron Parse) for parsing clinical PDF documents with OCR and table extraction.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fhir-synthetic-mcp List all patients"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agents propose. A deterministic layer validates. A human approves. Every action is audited.
A production-grade reference implementation for deploying LLM agents over clinical data with deterministic safety guardrails. Built as a reusable framework for healthcare operators — deploy once, apply across a portfolio.
Live demo: https://clinical-ai-governance-platform-production.up.railway.app
Raw PDF / prior auth letter / treatment plan
↓
parse_clinical_document (Nemotron Parse — NVIDIA NIM)
Multi-column OCR, table extraction, reading-order reconstruction
↓
de-identification layer (deidentify.py)
Strip name/MRN, hash patient ID, bucket age — before any external API
↓
extract_entities (ClinicalNLP — Anthropic structured output, temp=0)
ICD-10-CM · LOINC · NPI · RxNorm · calibrated confidence
↓
search_guidelines (RAG — BM25 + ChromaDB hybrid, RRF fusion)
Evidence-based thresholds from 8 clinical guidelines
↓
search_clinical_trials (ClinicalTrials.gov v2 API — on flagged observations)
Recruiting trials the patient may qualify for
↓
propose_observation (LOINC deterministic gate — 14 codes)
Hard reject on impossible values · warning on clinical flags
↓
══ HUMAN-IN-THE-LOOP GATE ══
approve_write / reject_write (verified approver only, DUA-gated)
↓
SQLite commit (WAL mode, FK enforcement, field-level encryption)
↓
SHA-256 audit chain (tamper-evident JSONL, verify_chain())Related MCP server: FHIR MCP Server
┌─────────────────────────────────────────────────────────────────────┐
│ Clinical AI Governance Platform │
│ │
│ [IN] Nemotron Parse (NVIDIA NIM / self-hosted for PHI) │
│ Raw PDF → structured markdown (prior auth, EOB, plan) │
│ │ │
│ ▼ │
│ De-identification layer (deidentify.py) │
│ Hash patient ID · strip name/MRN · bucket age │
│ │ │
│ ▼ │
│ Agent SDK Orchestration (src/clinical_agent/) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Reader │→ │ RAG │→ │ Proposal │ │
│ │ Subagent │ │ Subagent │ │ Subagent │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ PostToolUse hooks: audit logging + cost/latency tracking │
│ │ │
│ MCP Server (FastMCP 3.x) 10 tools · 2 resources │
│ │ │
│ Deterministic Validation (validator.py) │
│ LOINC registry · value ranges · unit enforcement │
│ │ │
│ Auth + DUA layer (auth.py) │
│ Principal · Approver · Data Use Agreement verification │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ SQLite Store │ │ ChromaDB RAG │ │ Audit Chain │ │
│ │ WAL · FK │ │ BM25+Semantic│ │ SHA-256 JSONL │ │
│ │ Fernet enc. │ │ RRF fusion │ │ verify_chain() │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ │
│ ClinicalTrials.gov v2 · Eval harness (25 cases, LLM-judge) │
└─────────────────────────────────────────────────────────────────────┘Component | Status |
SQLite persistence (WAL, FK) | ✓ Day 1 |
Tamper-evident audit (SHA-256 chain) | ✓ Day 1 |
Auth (principal + approver verification) | ✓ Day 1 |
LOINC deterministic validation (14 codes) | ✓ Day 2 |
Clinical data (8 guidelines, 4 notes) | ✓ Day 2 |
MCP resources + prompts + prompt caching | ✓ Day 2 |
RAG — BM25 + ChromaDB hybrid (RRF) | ✓ Day 3 |
Agent SDK orchestration (3 subagents, hooks) | ✓ Day 4 |
Extended thinking routing (flagged proposals) | ✓ Day 4 |
Clinical NLP entity extraction (structured output) | ✓ Day 5 |
Calibrated confidence scoring (Brier score) | ✓ Day 5 |
Eval harness (25 golden cases, LLM-as-judge) | ✓ Day 6 |
GitHub Actions CI (pytest + eval regression gate) | ✓ Day 6 |
HTTP server (FastAPI SSE, claude.ai connector) | ✓ Day 7 |
Dockerfile + Railway deploy | ✓ Day 7 |
ClinicalTrials.gov integration | ✓ Day 8 |
Nemotron Parse — raw PDF → structured text → NLP → audit | ✓ Day 9 |
DUA enforcement ( | ✓ Day 10 |
Field-level encryption at rest (Fernet, PHI fields) | ✓ Day 10 |
De-identification layer (hash ID, strip name/MRN, age bucket) | ✓ Day 10 |
Metric | Value |
Accuracy (accept/reject correct) | 100% |
False-negative rate | 0% |
Regression threshold | 80% |
Brier score | 0.3174 |
Mean validation latency | 0.32 ms |
Eval suite size | 25 golden cases |
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python3 scripts/seed_db.py
pytest -qclaude mcp add clinical-governance -- \
/path/to/.venv/bin/python -m fhir_mcp.serverSettings → Connectors → Add → https://clinical-ai-governance-platform-production.up.railway.app/sse
Variable | Default | Purpose |
| — | Required for Agent SDK + NLP |
| — | Required for Nemotron Parse (NVIDIA NIM) |
| NIM cloud | Override with self-hosted NIM URL for PHI docs |
|
| Set |
| — | Fernet key for PHI field encryption at rest |
| — | Comma-separated actor IDs with signed DUA |
|
| SQLite database path |
|
| Agent audit identity |
| stderr | Audit JSONL path |
|
| LOINC validation rules |
| (unset = dev mode) | Allowed agent actor IDs |
| (unset = dev mode) | Allowed human approver IDs |
|
| Set |
|
| HTTP server port |
python3 -c "from fhir_mcp.store import generate_encryption_key; print(generate_encryption_key())"Store the output in your secrets manager as FHIR_MCP_ENCRYPTION_KEY.
python3 scripts/audit_verify.py data/audit.jsonlpython3 scripts/run_evals.py --suite smoke
python3 scripts/run_evals.py --suite full --judgesrc/
fhir_mcp/
server.py FastMCP 10 tools + resources + prompts
store.py SQLite store + field-level encryption (only PHI touchpoint)
models.py Pydantic v2 FHIR models
audit.py SHA-256 hash-chain audit
auth.py Principal + approver + DUA verification
validator.py LOINC deterministic gate
deidentify.py De-identification layer (hash ID, strip PHI, age bucket)
rag.py BM25 + ChromaDB hybrid RAG
nlp.py Clinical NLP entity extraction
confidence.py Calibrated confidence scoring
trials.py ClinicalTrials.gov v2 API client
parse.py Nemotron Parse (NVIDIA NIM) client
http_server.py FastAPI SSE transport
clinical_agent/
orchestrator.py ClinicalOrchestrator (3-subagent workflow)
subagents.py Reader / RAG / Proposal subagent configs
hooks.py PostToolUse audit + cost hook
evals/
golden_dataset.json 25 test cases
runner.py Code-based + LLM-as-judge grading
judge_prompt.py LLM-as-judge prompt template
mimic_cdm_eval.py MIMIC-CDM 4-axis governance agent eval
data/
synthetic_patients.json Seed data
loinc_rules.json 14 LOINC validation rules
clinical_guidelines.json 8 evidence-based guidelines
clinical_notes.json 4 synthetic notes
scripts/
seed_db.py JSON → SQLite
audit_verify.py Chain integrity verifier
run_agent.py Agent SDK CLI
run_evals.py Eval harness CLI
docs/
architecture.md Full system design + diagrams
adr/ 4 Architecture Decision Records
scale.md Portfolio deployment playbook
ci.md GitHub Actions setupDay | Milestone |
1 | SQLite store, tamper-evident audit, auth layer |
2 | LOINC validator + clinical data (guidelines, notes) |
3 | RAG: BM25 + ChromaDB hybrid over clinical guidelines |
4 | Agent SDK orchestration (Reader/RAG/Proposal subagents, hooks) |
5 | Clinical NLP entity extraction + calibrated confidence scoring |
6 | Eval harness: golden dataset, LLM-as-judge, GitHub Actions CI |
7 | HTTP server (FastAPI SSE), Dockerfile, Railway deploy |
8 | ClinicalTrials.gov integration: surface recruiting trials on flagged observations |
9 | Nemotron Parse: raw PDF → structured text → NLP → validation → audit |
10 | PHI infrastructure: DUA enforcement, field-level encryption, de-identification layer |
Four datasets ground the system across two sub-projects. Each is academically sourced, operates on de-identified or synthetic data, and has a dedicated evaluation methodology drawn from peer-reviewed literature.
Academic source
Ben Abacha, A., & Demner-Fushman, D. (2019). A question-entailment approach to question answering. BMC Bioinformatics, 20(1), 511. https://doi.org/10.1186/s12859-019-3119-4
47,457 question–answer pairs sourced from 12 NIH websites (MedlinePlus, CancerGov, NIDDK, NINDS, GARD, and others). Covers 37 question types across common and rare diseases. License: CC BY 4.0. No PHI — all content is public NIH patient education material.
Location: evidence_pipeline/datasets/medquad.py
LLM architecture — entity linking via deterministic crosswalk
Each QA pair carries a focus (condition name) and optional UMLS CUI gold label. The pipeline maps focus → CUI via ontology/cui_mapper.py — fully deterministic, no LLM in the mapping step. The LLM role is upstream: clinical question generation and metatag refinement.
Test suite — evidence_pipeline/tests/test_datasets.py
Dataset structure, field validation, is_answered / has_gold_cui / is_rare_disease properties, CSV and XML format compatibility.
LLM reasoning framework — BioEL entity linking
Sung, M., Jeon, H., Lee, J., & Kang, J. (2020). Biomedical Entity Representations with Synonym Marginalization. arXiv:2005.00239. https://arxiv.org/abs/2005.00239
Implemented in evidence_pipeline/evals/entity_linking.py and runner.py. Top-k accuracy and Mean Reciprocal Rank (MRR) over the full corpus.
Metric | Smoke target | Full corpus |
Top-1 accuracy | 100% | graded |
Top-5 accuracy | 100% | graded |
MRR | 1.0 | graded |
Coverage (gold CUI present) | 100% | graded |
Academic source
Johnson, A.E.W., Bulgarelli, L., Shen, L., Gayles, A., Shammout, A., Horng, S., Pollard, T.J., Hao, S., Moody, B., Gow, B., Lehman, L.H., Celi, L.A., & Mark, R.G. (2023). MIMIC-IV, a freely accessible electronic health record dataset. Scientific Data, 10, 1. https://doi.org/10.1038/s41597-022-01899-x
Goldberger, A.L., Amaral, L.A.N., Glass, L., Hausdorff, J.M., Ivanov, P.Ch., Mark, R.G., Mietus, J.E., Moody, G.B., Peng, C.K., & Stanley, H.E. (2000). PhysioBank, PhysioToolkit, and PhysioNet. Circulation, 101(23), e215–e220. https://doi.org/10.1161/01.CIR.101.23.e215
De-identified ICU discharge summaries from Beth Israel Deaconess Medical Center. Demo subset (100 patients): physionet.org/content/mimic-iv-demo/ — free PhysioNet account, no CITI training. Full dataset requires CITI training + signed DUA. PHI note: loader logs note_id only, never raw text.
Location: evidence_pipeline/datasets/mimic.py, evidence_pipeline/extraction/loinc_extractor.py, evidence_pipeline/pipeline/end_to_end.py
LLM architecture — deterministic extraction + governance gate
24 regex patterns extract LOINC-coded observations from discharge text (zero LLM in extraction). The HumanGate class enforces the core governance invariant: every proposed observation is queued with a full audit entry (who/what/when/why) and committed = 0 in automated mode. Human .approve() is required to commit — wiring to src/fhir_mcp/store.py in production.
Test suite — evidence_pipeline/tests/test_mimic.py, test_loinc_extractor.py, test_end_to_end.py
5 dataset tests, 14 LOINC extraction tests, 7 end-to-end tests including core governance invariant (committed == 0).
LLM reasoning framework — FACTS Grounding
Jacovi, A., Caciularu, A., Goldman, O., & Goldberg, Y. (2025). FACTS Grounding: A New Benchmark for Evaluating the Factuality of Large Language Models. arXiv:2501.03200. https://arxiv.org/abs/2501.03200
Implemented in evidence_pipeline/evals/grounding.py. Every ICD-10, RxNorm, LOINC, CUI, and NCT-ID in pipeline output is checked against its canonical source. Grounding score = attributable_claims / total_claims. Score of 1.0 = zero unattributed claims.
Outcome metric (measured, 10 synthetic notes):
Extracted 62 LOINC-coded observations from 10 synthetic discharge notes, 100% validated, 0% rejected by deterministic gate, 0 committed without human approval.
python evidence_pipeline/demo_mimic.py # synthetic
python evidence_pipeline/demo_mimic.py --notes-dir /path/to/mimic # real MIMIC-IV DemoAcademic source
Hager, P., Jungmann, F., Holland, R., Bhagat, K., Hubrecht, I., Knauer, M., Vielhauer, J., Makowski, M., Braren, R., Kaissis, G., & Rueckert, D. (2024). Evaluation and mitigation of the limitations of large language models in clinical decision-making. Nature Medicine. https://doi.org/10.1038/s41591-024-03097-1
Hager, P., Jungmann, F., & Rueckert, D. (2024). MIMIC-IV-Ext Clinical Decision Making (version 1.0). PhysioNet. https://doi.org/10.13026/2pfq-5b68
Derived from MIMIC-IV. Evaluates LLMs on 4-axis clinical decision making given a patient presentation. Available at physionet.org/content/mimic-iv-ext-cdm/. Leaderboard: huggingface.co/spaces/MIMIC-CDM/leaderboard.
Location: evidence_pipeline/datasets/mimic_cdm.py, evidence_pipeline/evals/clinical_decision.py, evals/mimic_cdm_eval.py
LLM architecture — dual-layer CDM eval
Two separate eval targets share the same CDMCase schema and CDMScore rubric:
evidence_pipeline/evals/clinical_decision.py — grades the evidence layer: does the ontology pipeline support correct decisions?
evals/mimic_cdm_eval.py — grades the governance agent (src/clinical_agent/orchestrator.py): does the LLM itself make correct decisions? CI uses a deterministic crosswalk-backed mock; production wires to live ClinicalOrchestrator.
Test suite — evidence_pipeline/tests/test_mimic_cdm.py
4 dataset structure tests, 4 F1 scoring unit tests, 3 CDM eval layer tests (composite ≥ 0.75 CI gate).
LLM reasoning framework — AMIE multi-axis auto-rater
Tu, T., Palepu, A., Schaekermann, M., Saab, K., Freyberg, J., Tanno, R., Wang, A., Li, B., Amin, M., Tomasev, N., Ghassemi, M., Azizi, S., Kannan, A., Chou, K., Hassidim, A., Matias, Y., Xu, Y., Singhal, K., Gottweis, J., & Natarajan, V. (2024). Towards conversational diagnostic AI. arXiv:2401.05654. https://arxiv.org/abs/2401.05654
Token-level F1 per axis against gold ICD-10 / RxNorm / LOINC / CPT labels. Composite = mean across 4 axes. CI gate: composite ≥ 0.75.
Axis | Gold standard | CI target |
Diagnosis accuracy | ICD-10 F1 | ≥ 0.75 |
Treatment accuracy | RxNorm F1 | ≥ 0.75 |
Lab ordering accuracy | LOINC F1 | ≥ 0.75 |
Procedure accuracy | CPT F1 | ≥ 0.75 |
Composite | mean | ≥ 0.75 |
Source: Internal synthetic dataset, no PHI. Designed against the LOINC validation rules in data/loinc_rules.json and 8 clinical guidelines in data/clinical_guidelines.json.
Location: evals/golden_dataset.json, evals/runner.py, evals/judge_prompt.py
LLM architecture — code-based + LLM-as-judge 25 cases covering accept / reject / borderline observations across 14 LOINC codes. Deterministic code-based grading (exact accept/reject match) plus LLM-as-judge for reasoning quality. Calibrated confidence scoring uses the Brier score:
Brier, G.W. (1950). Verification of Forecasts Expressed in Terms of Probability. Monthly Weather Review, 78(1), 1–3. https://doi.org/10.1175/1520-0493(1950)078<0001:VOFEIT>2.0.CO;2
Test suite — evals/runner.py
Code-based accuracy + false-negative rate, LLM-as-judge reasoning quality, calibrated Brier score.
LLM reasoning framework — LLM-as-judge
Zheng, L., Chiang, W.L., Sheng, Y., Zhuang, S., Wu, Z., Zhuang, Y., Lin, Z., Li, Z., Li, D., Xing, E.P., Zhang, H., Gonzalez, J.E., & Stoica, I. (2023). Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena. arXiv:2306.05685. https://arxiv.org/abs/2306.05685
Metric | Value |
Accuracy (accept/reject) | 100% |
False-negative rate | 0% |
Brier score | 0.3174 |
Regression threshold | 80% |
All four datasets share a common ontological foundation: the UMLS Concept Unique Identifier (CUI) as the canonical hub linking ICD-10-CM, RxNorm, LOINC, SNOMED CT, and CPT-4.
Bodenreider, O. (2004). The Unified Medical Language System (UMLS): integrating biomedical terminology. Nucleic Acids Research, 32(suppl_1), D267–D270. https://doi.org/10.1093/nar/gkh061
Vocabulary | Authority | Citation |
ICD-10-CM | WHO / CMS | World Health Organization. (2019). International Statistical Classification of Diseases (10th ed.). |
RxNorm | NLM | Nelson, S.J., Zeng, K., Kilbourne, J., Powell, T., & Moore, R. (2011). Normalized names for clinical drugs: RxNorm at 6 years. JAMIA, 18(4), 441–448. https://doi.org/10.1136/amiajnl-2011-000116 |
LOINC | Regenstrief Institute | McDonald, C.J., et al. (2003). LOINC, a universal standard for identifying laboratory observations. Clinical Chemistry, 49(4), 624–633. https://doi.org/10.1373/49.4.624 |
SNOMED CT | SNOMED International | Donnelly, K. (2006). SNOMED-CT: The advanced terminology and coding system for eHealth. Studies in Health Technology and Informatics, 121, 279–290. |
CPT-4 | AMA | American Medical Association. (2023). Current Procedural Terminology: CPT 2024. AMA Press. |
Implementation: evidence_pipeline/ontology/cui_mapper.py — 13 conditions, deterministic lookup, zero hallucination. Grounding validated by evidence_pipeline/evals/grounding.py (FACTS Grounding, Jacovi et al. 2025).
A sub-project built on top of this governance platform — zero changes to any
src/file.
The governance platform answers how to safely deploy clinical agents. This companion demonstrates what those agents generate: structured, evidence-backed clinical content at scale — directly aligned with real-world evidence (RWE) generation workflows.
Clinical question (e.g. "paroxysmal nocturnal hemoglobinuria")
↓
evidence_pipeline/datasets/medquad.py 47,457 NIH QA pairs (CC BY 4.0)
question types · UMLS CUI labels
common conditions + GARD rare diseases
↓
evidence_pipeline/ontology/cui_mapper.py UMLS CUI → ICD-10-CM / RxNorm / LOINC
SNOMED CT / CPT-4 crosswalk
deterministic lookup — no hallucination
↓
Live APIs ClinicalTrials.gov v2 (recruiting trials)
CMS Medicare Coverage Database (NCDs + LCDs)
↓
evidence_pipeline/demo.py Structured, metatagged JSON output
optimised for search and retrieval indexing
↓
evidence_pipeline/demo_mimic.py End-to-end outcome metric
62 LOINC observations · 100% validated
0 committed without human approvalKey design principle: the cui_mapper.py crosswalk is the deterministic validation gate for ontology codes — the same agent-proposes / deterministic-validates pattern as validator.py in the main platform.
Quick demo (no API key required):
# Condition evidence brief
python evidence_pipeline/demo.py "paroxysmal nocturnal hemoglobinuria"
# → ICD-10 D59.5 CUI C0028344 RxNorm 727910 (eculizumab)
# → 5 recruiting trials CMS coverage queried metatagged JSON output
# End-to-end MIMIC-IV pipeline (synthetic notes, zero PHI)
python evidence_pipeline/demo_mimic.py
# → Extracted 62 LOINC observations from 10 notes
# → 100% validated, 0% rejected, 0 committed without human approvalHUMAN-IN-THE-LOOP GATE. Commit a staged write.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| approver | Yes | ||
| write_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of disclosing behavior. It only states that the tool commits a staged write after human approval, but does not describe consequences (e.g., whether the write becomes irreversible, approval requirements, or what happens on failure).
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 brief and front-loaded with a clear purpose, but it is under-specified given the three required parameters and workflow context. It reads as concise without being sufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is part of a human-in-the-loop workflow (with propose_observation, list_pending_writes, reject_write), and has three required parameters plus an output schema. The description does not place approve_write in this workflow, explain where write_id comes from, or indicate what the output will contain. This leaves critical context missing.
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 0% and the description itself provides no information about write_id, approver, or reason. The description utterly fails to compensate for the lack of schema-level parameter documentation, leaving all three required parameters undefined.
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 identifies a clear action ('Commit a staged write') and a specific resource, which distinguishes it from the sibling reject_write. It doesn't explicitly name alternatives or scope limitations, so it doesn't earn a 5.
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 phrase 'HUMAN-IN-THE-LOOP GATE' implies this tool is used when human approval is required for a pending write. However, there is no explicit 'when to use vs alternatives', no mention of reject_write or list_pending_writes as counterparts, and no prerequisites for obtaining write_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one patient's demographics. reason is recorded in the audit trail.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| patient_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It uses 'Read' to signal read-only behavior and explicitly discloses that `reason` is recorded in the audit trail, a non-obvious side effect. This adds meaningful context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and includes only essential information. Every word contributes to understanding the tool's purpose and 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?
The tool is simple, has an output schema, and the description covers the key behavioral nuance (audit trail). It omits details like error conditions or access requirements, but for a straightforward read operation with structured output, this is adequate.
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 0%, and the description only explains `reason` (as being audited). `patient_id` is left to inference from its name, so the description partially compensates for the absent schema descriptions but does not fully clarify both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Read one patient's demographics' – a specific verb and resource that clearly distinguishes it from sibling tools like list_patients. The additional audit trail note further clarifies its scope.
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 phrase 'one patient' provides clear context for when to use this tool – when you need a single patient's demographics. It does not explicitly name alternatives or exclusions, but the distinction from list_patients is evident from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a patient's observations. reason is audited.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| patient_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that 'reason is audited', which is a useful behavioral trait. However, with no annotations provided, it fails to disclose other important behaviors such as read-only status, pagination, or error handling.
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 short sentences. It front-loads the primary purpose and adds the audit note as a caveat, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and only two parameters, but the description lacks usage guidance and detailed parameter semantics. The audit note is valuable but insufficient for a complete picture.
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 0%, so the description must compensate. It only mentions that 'reason is audited', which adds minimal context, but does not explain the purpose or format of either parameter, especially patient_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 'List a patient's observations', specifying the verb (list), resource (observations), and scope (patient's). This distinguishes it from sibling tools like list_patients and parse_clinical_document.
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. It doesn't mention when not to use it, or how it relates to related tools like search_guidelines or get_patient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available patient IDs. reason: why you need this list.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It implies a read-only operation but does not state rate limits, permissions, pagination, or the meaning of the required `reason` parameter. The purpose of `reason` and its potential effect on the response is unexplained, leaving the agent uncertain about side effects or constraints.
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 concise sentence plus a parenthetical parameter explanation. It front-loads the core purpose and wastes no words, earning a high score for conciseness and structure.
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?
Despite having an output schema, the tool lacks annotations and the description does not explain return behavior, the role of `reason`, or usage context relative to siblings. The presence of a required `reason` parameter is unusual and unexplained, creating a significant gap for a simple-looking tool. The description is minimally adequate but incomplete for a dependable agent decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero description coverage for the single parameter `reason`, so the description's phrase 'why you need this list' adds a minimal semantic: it is a justification string. However, it does not specify format, allowed values, length limits, or whether it affects the returned data, so compensation is partial.
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 'List available patient IDs' clearly states a specific verb+resource (list patients) and the output is patient IDs. It distinguishes somewhat from sibling get_patient by indicating a list operation, but does not clarify what 'available' means (all patients vs. accessible ones), which leaves some ambiguity.
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 list_observations or get_patient. The sole mention of `reason` hints at a use case (why you need the list) but does not provide explicit context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List writes awaiting human approval.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It only states 'List writes awaiting human approval,' which implies a read-only operation, but it does not clarify whether it has side effects, requires permissions, or how it handles the 'reason' parameter. This is too minimal for a tool with no annotation safety net.
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 concise sentence with no filler. It is front-loaded and to the point, but it sacrifices necessary details for brevity. Still, for what is included, it is 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?
Given the tool has one required parameter with no explanation and no annotations, the description is incomplete. The presence of an output schema may help with return values, but the description still does not explain the purpose of the 'reason' parameter or provide any behavioral context. The tool is simple, but the missing parameter semantics make it 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 description coverage is 0% and the description completely ignores the required 'reason' parameter. The schema provides only the parameter name and type, leaving the agent without any clue about what 'reason' means or how it filters results. The description fails to compensate for the missing parameter documentation.
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 ('List') and the specific resource ('writes awaiting human approval'), making it distinct from sibling tools like list_patients or approve_write. It leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used to see pending write approvals, but it does not explicitly state when to use it over alternatives or mention any prerequisites. It is understandable in the context of sibling tools like approve_write and reject_write, but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse a clinical document using Nemotron Parse (NVIDIA NIM).
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Why you are parsing this document (audited). | |
| source | Yes | File path, public URL, or base64-encoded document bytes. For PHI documents, use a self-hosted NIM endpoint (set NEMOTRON_PARSE_BASE_URL) so content stays on-prem. | |
| document_type | No | One of 'clinical', 'prior_auth', 'eob', 'treatment_plan', 'lab_report'. Guides the parser. | clinical |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It mentions using NVIDIA NIM, and the source parameter notes PHI handling via a self-hosted endpoint, implying potential external data transmission. However, it does not disclose side effects, permissions, rate limits, or what happens to the document. Partial disclosure 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 of 10 words, directly stating the tool's purpose without any extraneous information. It is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The full tool definition benefits from a fully described input schema and an output schema, which cover return values and parameter constraints. The description itself is terse but combined with schema it provides adequate context, though it could better summarize the overall behavior and side effects at a high level.
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% with detailed parameter descriptions (source types, PHI guidance, document_type options). The tool description itself adds no parameter-level detail, 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 a specific action ('Parse') on a distinct resource ('a clinical document') and specifies the technology ('Nemotron Parse (NVIDIA NIM)'). This differentiates it from sibling tools that handle patients, observations, guidelines, and writes.
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 itself gives a clear context for use (parsing clinical documents). The parameter description for 'source' provides practical guidance for PHI documents (using a self-hosted NIM endpoint). No explicit alternatives or exclusions are mentioned, but the use case is unambiguous relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose a new observation. Stages it for human approval; does NOT write.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| unit | Yes | ||
| value | Yes | ||
| reason | Yes | ||
| display | Yes | ||
| patient_id | Yes | ||
| effective_date | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. It explicitly states 'does NOT write' and 'stages for human approval', which are critical behavioral traits. It omits details like reversibility or error conditions, but the most important side-effect disclosure is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the main purpose, and every clause adds meaningful information. It is concise without losing clarity.
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?
Despite having 7 required parameters with zero schema descriptions and no annotations, the description provides no parameter context or workflow guidance. The presence of an output schema covers return values, but the description still leaves major gaps in how to construct a valid proposal and what happens after staging.
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 0%, so the description must compensate by explaining the 7 required parameters. It does not mention any parameter, leaving the agent to infer meanings from names alone. No format, code system, or relationship guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Propose a new observation') and the resource. The added clause 'Stages it for human approval; does NOT write' distinguishes it from direct write tools like approve_write and from read-only list_observations.
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 a staging workflow that precedes approval, signaling when to use this tool versus approve_write. It does not explicitly name sibling tools or state exclusions, but the context is clear enough for an agent to infer the intended workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
HUMAN-IN-THE-LOOP GATE. Reject a staged write.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| approver | Yes | ||
| write_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only offers the vague label 'HUMAN-IN-THE-LOOP GATE' and the core action. It does not disclose consequences of rejection, permissions required, reversibility, or side effects.
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 brief, but this brevity is due to under-specification rather than economy. The 'HUMAN-IN-THE-LOOP GATE' label adds little concrete information, and the action sentence is minimal. Lacks essential details that should be included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is part of a write approval workflow, as evidenced by siblings approve_write and list_pending_writes. The description fails to explain this context, what a 'staged write' is, or the consequences of rejection. With three unexplained parameters and no annotations, the description is completely inadequate for a reliable tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero descriptions for the three required parameters (write_id, approver, reason). The description does not explain any of them, leaving their meaning to inference. With 0% schema coverage, the description was expected to compensate but did not.
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 states 'Reject a staged write' which is a specific action targeting a specific resource type (a staged write). It is clear and likely understood in the context of the sibling tool approve_write, though it does not explicitly name that alternative.
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 versus approve_write or other alternatives. The sibling tools list_pending_writes and approve_write suggest a workflow, but the description does not explain the decision criteria for rejecting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ClinicalTrials.gov for recruiting trials matching a condition.
Call when search_guidelines returns validation_warnings (flagged observations) to surface trials the patient may qualify for. PHI-safe: only condition strings transmitted externally.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| condition | Yes | ||
| loinc_codes | No | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds a crucial safety disclosure: 'PHI-safe: only condition strings transmitted externally.' This tells the agent that the tool does not send protected health information beyond the condition, which is critical in a medical context. It also implies a read-only search. However, it does not elaborate on other behaviors like rate limits or error handling, so it gets a 4.
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 that front-load the primary purpose and then add usage and safety context. There is no fluff or redundant content; every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers the return structure, so the description needn't explain return values. It covers the primary trigger and safety. However, it omits explanations for three of four parameters and does not describe the relationship with search_guidelines beyond the trigger. This is a clear gap, making the description adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning all four parameters (condition, reason, loinc_codes, max_results) lack descriptions. The description only mentions 'condition', which maps to one parameter. The remaining parameters are non-obvious, and the schema only provides defaults and types, not semantics. Thus the description fails to compensate for the coverage gap.
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 starts with a specific action verb 'Search' and clearly identifies the resource (ClinicalTrials.gov) and the scope (recruiting trials matching a condition). This distinguishes it from sibling tools like search_guidelines or list_observations, which are about different resources or actions.
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 call the tool: 'Call when search_guidelines returns validation_warnings (flagged observations) to surface trials the patient may qualify for.' This gives clear situational context, but it does not explicitly mention when not to use it or present alternatives, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search clinical guidelines using hybrid BM25 + semantic retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| query | Yes | ||
| reason | No | ||
| loinc_codes | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It mentions the hybrid retrieval method, which is a useful behavioral detail, but it does not explicitly state that this is a read-only operation, mention any authentication requirements, or describe rate limits or side effects. This is partial transparency but lacks a clear safety profile.
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, front-loaded sentence with no filler. It wastes no words and is easily scannable. This is ideal for conciseness.
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?
Despite having an output schema, the description is sparse for a tool with 4 parameters and no annotations. It does not differentiate the tool from sibling search_clinical_trials, explain parameter semantics, or provide usage context. The minimalism leaves the agent with significant gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the tool description does not explain any parameters. Parameter names like 'k', 'reason', and 'loinc_codes' are ambiguous without additional context. The description fails to compensate for the lack of schema parameter descriptions.
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 (search) and the resource (clinical guidelines), and specifies the retrieval method (hybrid BM25 + semantic retrieval). It effectively distinguishes this tool from sibling 'search_clinical_trials' by focusing on guidelines. This is a specific verb+resource statement.
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 versus alternatives like search_clinical_trials, nor does it mention any prerequisites or exclusions. It only states what the tool does, leaving the agent to infer usage from the name. This is a lack of explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action and resource: listing vs reading patients, searching guidelines vs trials, proposing vs approving/rejecting writes. No two tools appear to do the same thing.
All tool names follow a consistent snake_case verb_noun pattern (list_patients, get_patient, search_guidelines, approve_write). The convention is uniform across the entire set.
With 10 tools, the server is well-scoped for its purpose: patient data access, clinical searches, and a human-in-the-loop write workflow. Each tool serves a clear role without excessive overlap or bloat.
The core workflow is covered: list/get patients, list observations, propose and approve/reject observations, plus guideline and trial searches. Minor gaps exist (e.g., no update/delete for observations, no patient creation), but these are not critical for the synthetic FHIR use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Remote MCP for MCP consent scope receipt, structured receipts, audit logs, and reviewer-ready eviden
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
Privacy-preserving synthetic health data generation. FHIR R4/R5 compliant.
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/KrishnaKakani-GitHub/clinical-ai-governance-platform'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
