mims-harvard/tooluniverse-clinical-trial-matching

Clinical Trial Matching for Precision Medicine

Transform patient molecular profiles and clinical characteristics into prioritized clinical trial recommendations. Searches ClinicalTrials.gov and cross-references with molecular databases (CIViC, OpenTargets, ChEMBL, FDA) to produce evidence-graded, scored trial matches.

KEY PRINCIPLES:

1. Report-first approach - Create report file FIRST, then populate progressively
2. Patient-centric - Every recommendation considers the individual patient's profile
3. Molecular-first matching - Prioritize trials targeting patient's specific biomarkers

Molecular Matching Priority

Match patients to trials by molecular profile FIRST (specific mutations), then by disease stage, then by prior treatments. A patient with EGFR L858R should match to EGFR-targeted trials regardless of other factors. 4. Evidence-graded - Every recommendation has an evidence tier (T1-T4) 5. Quantitative scoring - Trial Match Score (0-100) for every trial 6. Eligibility-aware - Parse and evaluate inclusion/exclusion criteria 7. Actionable output - Clear next steps, contact info, enrollment status 8. Source-referenced - Every statement cites the tool/database source 9. Completeness checklist - Mandatory section showing analysis coverage 10. English-first queries - Always use English terms in tool calls. Respond in user's language

LOOK UP, DON'T GUESS

When uncertain about any scientific fact, SEARCH databases first rather than reasoning from memory. A database-verified answer is always more reliable than a guess.

---

COMPUTE, DON'T DESCRIBE

When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

When to Use

Apply when user asks:

• "What clinical trials are available for my NSCLC with EGFR L858R?"
• "Patient has BRAF V600E melanoma, failed ipilimumab - what trials?"
• "Find basket trials for NTRK fusion"
• "Breast cancer with HER2 amplification, post-CDK4/6 inhibitor trials"
• "KRAS G12C colorectal cancer clinical trials"
• "Immunotherapy trials for TMB-high solid tumors"
• "Clinical trials near Boston for lung cancer"
• "What are my options after failing osimertinib for EGFR+ NSCLC?"

NOT for (use other skills instead):

• Single variant interpretation without trial focus -> Use tooluniverse-cancer-variant-interpretation
• Drug safety profiling -> Use tooluniverse-adverse-event-detection
• Target validation -> Use tooluniverse-drug-target-validation
• General disease research -> Use tooluniverse-disease-research

---

Input Parsing

Required Input

• Disease/cancer type: Free-text disease name (e.g., "non-small cell lung cancer", "melanoma")

Strongly Recommended

• Molecular alterations: One or more biomarkers (e.g., "EGFR L858R", "KRAS G12C", "PD-L1 50%", "TMB-high")
• Stage/grade: Disease stage (e.g., "Stage IV", "metastatic", "locally advanced")
• Prior treatments: Previous therapies and outcomes (e.g., "failed platinum chemotherapy", "progressed on osimertinib")

Optional

• Performance status: ECOG or Karnofsky score
• Geographic location: City/state for proximity filtering
• Trial phase preference: I, II, III, IV, or "any"
• Intervention type: drug, biological, device, etc.
• Recruiting status preference: recruiting, not yet recruiting, active

For biomarker parsing rules and gene symbol normalization, see MATCHING_ALGORITHMS.md.

---

Workflow Overview

Input: Patient profile (disease + biomarkers + stage + prior treatments)

Phase 1: Patient Profile Standardization
  - Resolve disease to EFO/ontology IDs (OpenTargets, OLS)
  - Parse molecular alterations to gene + variant
  - Resolve gene symbols to Ensembl/Entrez IDs (MyGene)
  - Classify biomarker actionability (FDA-approved vs investigational)

Phase 2: Broad Trial Discovery
  - Disease-based trial search (ClinicalTrials.gov)
  - Biomarker-specific trial search
  - Intervention-based search (for known drugs targeting patient's biomarkers)
  - Deduplicate and collect NCT IDs

Phase 3: Trial Characterization (batch, groups of 10)
  - Eligibility criteria, conditions/interventions, locations, status, descriptions

Phase 4: Molecular Eligibility Matching
  - Parse eligibility text for biomarker requirements
  - Match patient's molecular profile to trial requirements
  - Score molecular eligibility (0-40 points)

Phase 5: Drug-Biomarker Alignment
  - Identify trial intervention drugs and mechanisms (OpenTargets, ChEMBL)
  - FDA approval status for biomarker-drug combinations
  - Classify drugs (targeted therapy, immunotherapy, chemotherapy)

Phase 6: Evidence Assessment
  - FDA-approved biomarker-drug combinations
  - Clinical trial results (PubMed), CIViC evidence, PharmGKB
  - Evidence tier classification (T1-T4)

Phase 7: Geographic & Feasibility Analysis
  - Trial site locations, enrollment status, proximity scoring

Phase 8: Alternative Options
  - Basket trials, expanded access, related studies

Phase 9: Scoring & Ranking (0-100 composite score)
  - Tier classification: Optimal (80-100) / Good (60-79) / Possible (40-59) / Exploratory (0-39)

Phase 10: Report Synthesis
  - Executive summary, ranked trial list, evidence grading, completeness checklist

---

Critical Tool Parameters

Clinical Trial Search Tools

| Tool | Key Parameters | Notes | |------|---------------|-------| | search_clinical_trials | query_term (REQ), condition, intervention, pageSize | Main search (ClinicalTrials.gov, U.S./global) | | search_clinical_trials | action="search_studies" (REQ), condition, intervention, limit | Alternative search | | get_clinical_trial_descriptions | action="get_study_details" (REQ), nct_id (REQ) | Full trial details | | CTIS_search_trials | query (REQ), limit, page | EU/EEA trials (EU CTIS register, since 2022) — complements ClinicalTrials.gov | | CTIS_get_trial | ct_number (REQ, e.g. 2022-503001-38-01) | Full EU trial detail (Part I/II, member states, results) | | ISRCTN_search_trials | query (REQ), limit | ISRCTN registry (UK-based, WHO-primary, international) — a third source | | ISRCTN_get_trial | isrctn_id (REQ, e.g. ISRCTN12336055) | Full ISRCTN trial detail + cross-ref ids (DOI/EudraCT/NCT) |

Geographic coverage: ClinicalTrials.gov is U.S.-centric but global; many EU/EEA-only trials appear only in the EU CTIS register, and UK/international trials in ISRCTN. For a comprehensive search — or any patient who could enroll outside the U.S. — query search_clinical_trials, CTIS_search_trials, and ISRCTN_search_trials, then merge (the three registers list largely disjoint trials; ISRCTN records carry DOI/EudraCT/NCT cross-refs you can use to dedupe against the others). Each register has its own id namespace and detail tool: NCT→get_clinical_trial_*, CT number→CTIS_get_trial, ISRCTN id→ISRCTN_get_trial.

Batch Trial Detail Tools (all take nct_ids array)

| Tool | Second Required Param | Returns | |------|----------------------|---------| | get_clinical_trial_eligibility_criteria | eligibility_criteria="all" | Eligibility text | | get_clinical_trial_locations | location="all" | Site locations | | get_clinical_trial_conditions_and_interventions | condition_and_intervention="all" | Arms/interventions | | get_clinical_trial_status_and_dates | status_and_date="all" | Status/dates | | get_clinical_trial_descriptions | description_type="brief" or "full" | Titles/summaries | | get_clinical_trial_outcome_measures | outcome_measures="all" | Outcomes |

Gene/Disease Resolution

| Tool | Key Parameters | |------|---------------| | MyGene_query_genes | query, species | | OpenTargets_get_disease_id_description_by_name | diseaseName | | OpenTargets_get_target_id_description_by_name | targetName | | ols_search_efo_terms | query, limit |

Drug Information

| Tool | Key Parameters | Notes | |------|---------------|-------| | OpenTargets_get_drug_id_description_by_name | drugName | Resolve drug to ChEMBL ID | | OpenTargets_get_drug_mechanisms_of_action_by_chemblId | chemblId | Drug MoA and targets | | OpenTargets_get_associated_drugs_by_target_ensemblID | ensemblId, size | Drugs for a target | | drugbank_get_targets_by_drug_name_or_drugbank_id | query, case_sensitive, exact_match, limit (ALL REQ) | Drug targets | | fda_pharmacogenomic_biomarkers | (none) | FDA biomarker-drug list | | FDA_get_indications_by_drug_name | drug_name, limit | FDA indications |

Evidence Tools

| Tool | Key Parameters | |------|---------------| | PubMed_search_articles | query, max_results | | civic_get_variants_by_gene | gene_id (CIViC int ID), limit | | PharmGKB_search_genes | query |

Known CIViC Gene IDs

EGFR=19, BRAF=5, ALK=1, ABL1=4, KRAS=30, TP53=45, ERBB2=20, NTRK1=197, NTRK2=560, NTRK3=561, PIK3CA=37, MET=52, ROS1=118, RET=122, BRCA1=2370, BRCA2=2371

Critical Parameter Notes

1. DrugBank tools: ALL 4 parameters (query, case_sensitive, exact_match, limit) are REQUIRED
2. search_clinical_trials: query_term is REQUIRED even for disease-only searches
3. search_clinical_trials: action must be exactly "search_studies"
4. CIViC civic_search_variants: Does NOT filter by query - returns alphabetically
5. CIViC civic_get_variants_by_gene: Takes CIViC gene ID (integer), NOT gene symbol
6. Batch clinical trial tools: Accept arrays of NCT IDs, process in batches of 10

---

Scoring Summary

Trial Match Score (0-100):

• Molecular Match: 0-40 pts (exact variant=40, gene-level=30, pathway=20, none=10, excluded=0)
• Clinical Eligibility: 0-25 pts (all met=25, most=18, some=10, ineligible=0)
• Evidence Strength: 0-20 pts (FDA-approved=20, Phase III=15, Phase II=10, Phase I=5)
• Trial Phase: 0-10 pts (III=10, II=8, I/II=6, I=4)
• Geographic: 0-5 pts (local=5, same country=3, international=1)

Recommendation Tiers: Optimal (80-100), Good (60-79), Possible (40-59), Exploratory (0-39)

Evidence Tiers: T1 (FDA/guideline), T2 (Phase III), T3 (Phase I/II), T4 (computational)

For detailed scoring logic, see SCORING_CRITERIA.md.

---

Parallelization Strategy

Group 1 (Phase 1 - simultaneous):

• MyGene_query_genes per gene, OpenTargets disease search, ols_search_efo_terms, fda_pharmacogenomic_biomarkers

Group 2 (Phase 2 - simultaneous):

• search_clinical_trials by disease, biomarker, and intervention; search_clinical_trials alternative

Group 3 (Phase 3 - simultaneous):

• All batch detail tools (eligibility, interventions, locations, status, descriptions)

Group 4 (Phases 5-6 - per drug):

• Drug resolution, MoA, FDA indications, PubMed evidence

---

Error Handling

1. Wrap every tool call in try/except
2. Check for empty results and string error responses
3. Use fallback tools when primary fails (e.g., OLS if OpenTargets fails)
4. Document failures in completeness checklist
5. Never let one failure block the entire analysis

---

Reference Files

| File | Contents | |------|----------| | TOOLS_REFERENCE.md | Full tool inventory with parameters and response structures | | MATCHING_ALGORITHMS.md | Patient profile standardization, biomarker parsing, molecular eligibility matching, drug-biomarker alignment code | | SCORING_CRITERIA.md | Detailed scoring tables, molecular match logic, drug-biomarker alignment scoring | | REPORT_TEMPLATE.md | Full markdown report template with all sections | | TRIAL_SEARCH_PATTERNS.md | Search functions, batch retrieval, parallelization, common use patterns, edge cases | | EXAMPLES.md | Worked examples for different matching scenarios | | QUICK_START.md | Quick-start guide for common workflows |