SkillsSKILLS
Productivity

tooluniverse-immunotherapy-response-prediction▌

mims-harvard/tooluniverse · updated Apr 8, 2026

$npx skills add https://github.com/mims-harvard/tooluniverse --skill tooluniverse-immunotherapy-response-prediction
summary

Predict patient response to immune checkpoint inhibitors (ICIs) using multi-biomarker integration. Transforms a patient tumor profile (cancer type + mutations + biomarkers) into a quantitative ICI Response Score with drug-specific recommendations, resistance risk assessment, and monitoring plan.

skill.md

Immunotherapy Response Prediction

Predict patient response to immune checkpoint inhibitors (ICIs) using multi-biomarker integration. Transforms a patient tumor profile (cancer type + mutations + biomarkers) into a quantitative ICI Response Score with drug-specific recommendations, resistance risk assessment, and monitoring plan.

Reasoning Before Searching

Not all tumors respond to checkpoint inhibitors. Reason through the biology before running tools:

  • TMB (tumor mutational burden): More somatic mutations produce more neoantigens, which are recognized by T cells. High TMB (>=10 mut/Mb, FDA-approved threshold for pembrolizumab) generally predicts better response — but this varies by cancer type (e.g., RCC responds despite low TMB).
  • MSI-H (microsatellite instability-high): Caused by defective DNA mismatch repair (MMR). MSI-H tumors have very high TMB and are pan-cancer approved for pembrolizumab. Check MLH1, MSH2, MSH6, PMS2 mutations.
  • PD-L1 expression: The direct target of pembrolizumab/atezolizumab. High PD-L1 (TPS >=50% or CPS >=10 depending on cancer) predicts response in some cancers (NSCLC) but not all (melanoma, where TMB is more predictive).
  • Resistance factors are equally important: STK11, KEAP1, JAK1/2 loss, B2M mutations can render an otherwise TMB-high tumor non-responsive.

Before calling any tool, determine which biomarkers are available for this patient and which are unknown. This determines which phases can be scored with data vs. must use cancer-type priors. Do not default to "moderate" for unknowns — flag them explicitly as missing.

LOOK UP DON'T GUESS: Never assume FDA approval for a biomarker-ICI combination — always verify with fda_pharmacogenomic_biomarkers or FDA_get_indications_by_drug_name. Cancer-specific thresholds differ from pan-cancer approvals.

KEY PRINCIPLES:

  1. Report-first approach - Create report file FIRST, then populate progressively
  2. Evidence-graded - Every finding has an evidence tier (T1-T4)
  3. Quantitative output - ICI Response Score (0-100) with transparent component breakdown
  4. Cancer-specific - All thresholds and predictions are cancer-type adjusted
  5. Multi-biomarker - Integrate TMB + MSI + PD-L1 + neoantigen + mutations
  6. Resistance-aware - Always check for known resistance mutations (STK11, PTEN, JAK1/2, B2M)
  7. Drug-specific - Recommend specific ICI agents with evidence
  8. Source-referenced - Every statement cites the tool/database source
  9. English-first queries - Always use English terms in tool calls

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:

  • "Will this patient respond to immunotherapy?"
  • "Should I give pembrolizumab to this melanoma patient?"
  • "Patient has NSCLC with TMB 25, PD-L1 80% - predict ICI response"
  • "MSI-high colorectal cancer - which checkpoint inhibitor?"
  • "Patient has BRAF V600E melanoma, TMB 15 - immunotherapy or targeted?"
  • "Compare pembrolizumab vs nivolumab for this patient profile"

Input Parsing

Required: Cancer type + at least one of: mutation list OR TMB value Optional: PD-L1 expression, MSI status, immune infiltration data, HLA type, prior treatments, intended ICI

See INPUT_REFERENCE.md for input format examples, cancer type normalization, and gene symbol normalization tables.

Workflow Overview

Input: Cancer type + Mutations/TMB + Optional biomarkers (PD-L1, MSI, etc.)

Phase 1: Input Standardization & Cancer Context
Phase 2: TMB Analysis
Phase 3: Neoantigen Analysis
Phase 4: MSI/MMR Status Assessment
Phase 5: PD-L1 Expression Analysis
Phase 6: Immune Microenvironment Profiling
Phase 7: Mutation-Based Predictors
Phase 8: Clinical Evidence & ICI Options
Phase 9: Resistance Risk Assessment
Phase 10: Multi-Biomarker Score Integration
Phase 11: Clinical Recommendations

Phase 1: Input Standardization & Cancer Context

  1. Resolve cancer type to EFO ID via OpenTargets_get_disease_id_description_by_name
  2. Parse mutations into structured format: {gene, variant, type}
  3. Resolve gene IDs via MyGene_query_genes
  4. Look up cancer-specific ICI baseline ORR from the cancer context table (see SCORING_TABLES.md)

Phase 2: TMB Analysis

  1. Classify TMB: Very-Low (<5), Low (5-9.9), Intermediate (10-19.9), High (>=20)
  2. Check FDA TMB-H biomarker via fda_pharmacogenomic_biomarkers(drug_name='pembrolizumab')
  3. Apply cancer-specific TMB thresholds (see SCORING_TABLES.md)
  4. Note: RCC responds to ICIs despite low TMB; TMB is less predictive in some cancers

Phase 3: Neoantigen Analysis

  1. Estimate neoantigen burden: missense_count * 0.3 + frameshift_count * 1.5
  2. Check mutation impact via UniProt_get_function_by_accession
  3. Query known epitopes via iedb_search_epitopes
  4. POLE/POLD1 mutations indicate ultra-high neoantigen load

Phase 4: MSI/MMR Status Assessment

  1. Integrate MSI status if provided (MSI-H = 25 pts, MSS = 5 pts)
  2. Check mutations in MMR genes: MLH1, MSH2, MSH6, PMS2, EPCAM
  3. Check FDA MSI-H approvals via fda_pharmacogenomic_biomarkers(biomarker='Microsatellite Instability')

Phase 5: PD-L1 Expression Analysis

  1. Classify PD-L1: High (>=50%), Positive (1-49%), Negative (<1%)
  2. Apply cancer-specific PD-L1 thresholds and scoring methods (TPS vs CPS)
  3. Get baseline expression via HPA_get_cancer_prognostics_by_gene(gene_name='CD274')

Phase 6: Immune Microenvironment Profiling

  1. Query immune checkpoint gene expression for: CD274, PDCD1, CTLA4, LAG3, HAVCR2, TIGIT, CD8A, CD8B, GZMA, GZMB, PRF1, IFNG
  2. Classify tumor: Hot (T cell inflamed), Cold (immune desert), Immune excluded, Immune suppressed
  3. Run immune pathway enrichment via enrichr_gene_enrichment_analysis

Phase 7: Mutation-Based Predictors

  1. Resistance mutations (apply PENALTIES): STK11 (-10), PTEN (-5), JAK1/2 (-10 each), B2M (-15), KEAP1 (-5), MDM2/4 (-5), EGFR (-5)
  2. Sensitivity mutations (apply BONUSES): POLE (+10), POLD1 (+5), BRCA1/2 (+3), ARID1A (+3), PBRM1 (+5 RCC only)
  3. Check CIViC and OpenTargets for driver mutation ICI context
  4. Check DDR pathway genes: ATM, ATR, CHEK1/2, BRCA1/2, PALB2, RAD50, MRE11

Phase 8: Clinical Evidence & ICI Options

  1. Query FDA indications for ICI drugs via FDA_get_indications_by_drug_name
  2. Search clinical trials via search_clinical_trials (params: condition, intervention, query_term)
  3. Search PubMed for biomarker-specific response data
  4. Get drug mechanisms via OpenTargets_get_drug_mechanisms_of_action_by_chemblId

See SCORING_TABLES.md for ICI drug profiles and ChEMBL IDs.

Phase 9: Resistance Risk Assessment

  1. Check CIViC for resistance evidence via civic_search_evidence_items
  2. Assess pathway-level resistance: IFN-g signaling, antigen presentation, WNT/b-catenin, MAPK, PI3K/AKT/mTOR
  3. Summarize risk: Low / Moderate / High

Phase 10: Multi-Biomarker Score Integration

TOTAL SCORE = TMB_score + MSI_score + PDL1_score + Neoantigen_score + Mutation_bonus + Resistance_penalty

TMB_score:        5-30 points     MSI_score:        5-25 points
PDL1_score:       5-20 points     Neoantigen_score: 5-15 points
Mutation_bonus:   0-10 points     Resistance_penalty: -20 to 0 points

Floor: 0, Cap: 100

Response Likelihood Tiers:

  • 70-100 HIGH (50-80% ORR): Strong ICI candidate
  • 40-69 MODERATE (20-50% ORR): Consider ICI, combo preferred
  • 0-39 LOW (<20% ORR): ICI alone unlikely effective

Confidence: HIGH (all 4 biomarkers), MODERATE-HIGH (3/4), MODERATE (2/4), LOW (1), VERY LOW (cancer only)

Phase 11: Clinical Recommendations

  1. ICI drug selection using cancer-specific algorithm (see SCORING_TABLES.md)
  2. Monitoring plan: CT/MRI q8-12wk, ctDNA at 4-6wk, thyroid/liver function, irAEs
  3. Alternative strategies if LOW response: targeted therapy, chemotherapy, ICI+chemo combo, ICI+anti-angiogenic, ICI+CTLA-4 combo, clinical trials

Output Report

Save as immunotherapy_response_prediction_{cancer_type}.md. See REPORT_TEMPLATE.md for the full report structure.

Tool Parameter Reference

BEFORE calling ANY tool, verify parameters. See TOOLS_REFERENCE.md for verified tool parameters table.

Key reminders:

  • MyGene_query_genes: use query (NOT q)
  • EnsemblVEP_annotate_rsid: use variant_id (NOT rsid)
  • drugbank_* tools: ALL 4 params required (query, case_sensitive, exact_match, limit)
  • cBioPortal_get_mutations: gene_list is a STRING not array
  • ensembl_lookup_gene: REQUIRES species='homo_sapiens'

Evidence Tiers

Tier Description Source Examples
T1 FDA-approved biomarker/indication FDA labels, NCCN guidelines
T2 Phase 2-3 clinical trial evidence Published trial data, PubMed
T3 Preclinical/computational evidence Pathway analysis, in vitro data
T4 Expert opinion/case reports Case series, reviews

References