tooluniverse-cancer-variant-interpretation - Claude MCP Skill

# Cancer Variant Interpretation for Precision Oncology

Comprehensive clinical interpretation of somatic mutations in cancer. Transforms a gene + variant input into an actionable precision oncology report covering clinical evidence, therapeutic options, resistance mechanisms, clinical trials, and prognostic implications.

**KEY PRINCIPLES**:
1. **Report-first approach** - Create report file FIRST, then populate progressively
2. **Evidence-graded** - Every recommendation has an evidence tier (T1-T4)
3. **Actionable output** - Prioritized treatment options, not data dumps
4. **Clinical focus** - Answer "what should we treat with?" not "what databases exist?"
5. **Resistance-aware** - Always check for known resistance mechanisms
6. **Cancer-type specific** - Tailor all recommendations to the patient's cancer type when provided
7. **Source-referenced** - Every statement must cite the tool/database source
8. **English-first queries** - Always use English terms in tool calls (gene names, drug names, cancer types), even if the user writes in another language. Respond in the user's language

---

## LOOK UP, DON'T GUESS
When uncertain about any scientific fact, SEARCH databases first (PubMed, UniProt, ChEMBL, ClinVar, etc.) 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 treatments exist for EGFR L858R in lung cancer?"
- "Patient has BRAF V600E melanoma - what are the options?"
- "Is KRAS G12C targetable?"
- "Patient progressed on osimertinib - what's next?"
- "What clinical trials are available for PIK3CA E545K?"
- "Interpret this somatic mutation: TP53 R273H"

---

## Input Parsing

**Required**: Gene symbol + variant notation (e.g., "EGFR L858R", "BRAF p.V600E", "EML4-ALK fusion", "HER2 amplification")
**Optional**: Cancer type (improves specificity)

Parse the gene symbol and variant separately. For fusions, use the kinase partner as the primary gene. For amplifications/deletions, use the gene name directly. Normalize common aliases: HER2 -> ERBB2, PD-L1 -> CD274, VEGF -> VEGFA.

---

## Phase 0: Tool Parameter Verification (CRITICAL)

**BEFORE calling ANY tool for the first time**, verify its parameters.

| Tool | WRONG Parameter | CORRECT Parameter |
|------|-----------------|-------------------|
| `OpenTargets_get_associated_drugs_by_target_ensemblID` | `ensemblID` | `ensemblId` (camelCase) |
| `OpenTargets_get_drug_chembId_by_generic_name` | `genericName` | `drugName` |
| `OpenTargets_target_disease_evidence` | `ensemblID` | `ensemblId` + `efoId` |
| `MyGene_query_genes` | `q` | `query` |
| `search_clinical_trials` | `disease`, `biomarker` | `condition`, `query_term` (required) |
| `civic_get_variants_by_gene` | `gene_symbol` | `gene_id` (CIViC numeric ID) |
| `drugbank_*` | any 3 params | ALL 4 required: `query`, `case_sensitive`, `exact_match`, `limit` |
| `ChEMBL_get_drug_mechanisms` | `chembl_id` | `drug_chembl_id__exact` |
| `ensembl_lookup_gene` | no species | `species='homo_sapiens'` is REQUIRED |

---

## Workflow Overview

```
Input: Gene symbol + Variant notation + Optional cancer type

Phase 1: Gene Disambiguation & ID Resolution
  - Resolve gene to Ensembl ID, UniProt accession, Entrez ID
  - Get gene function, pathways, protein domains
  - Identify cancer type EFO ID (if cancer type provided)

Phase 2: Clinical Variant Evidence (CIViC)
  - Find gene in CIViC (via Entrez ID matching)
  - Get all variants for the gene, match specific variant
  - Retrieve evidence items (predictive, prognostic, diagnostic)

Phase 3: Mutation Prevalence (cBioPortal)
  - Frequency across cancer studies
  - Co-occurring mutations, cancer type distribution

Phase 4: Therapeutic Associations (OpenTargets + ChEMBL + FDA + DrugBank)
  - FDA-approved targeted therapies
  - Clinical trial drugs (phase 2-3), drug mechanisms
  - Combination therapies

Phase 5: Resistance Mechanisms
  - Known resistance variants (CIViC, literature)
  - Bypass pathway analysis (Reactome)

Phase 6: Clinical Trials
  - Active trials recruiting for this mutation
  - Trial phase, status, eligibility

Phase 7: Prognostic Impact & Pathway Context
  - Survival associations (literature)
  - Pathway context (Reactome), Expression data (GTEx)

Phase 8: Report Synthesis
  - Executive summary, clinical actionability score
  - Treatment recommendations (prioritized), completeness checklist
```

For detailed code snippets and API call patterns for each phase, see `ANALYSIS_DETAILS.md`.

---

## Clinical Reasoning Strategies

### Driver vs Passenger Reasoning

Not every mutation in a tumor is driving the cancer. Before querying databases, form a hypothesis:

- **Is this gene a known oncogene or tumor suppressor?** Genes like EGFR, BRAF, KRAS, TP53, PIK3CA are well-established cancer drivers. A mutation in one of these warrants deep investigation. A mutation in a gene with no known cancer role is likely a passenger.
- **Is this specific mutation recurrent across tumors (hotspot)?** Use cBioPortal to check prevalence across specific studies, or `GenomeNexus_get_cancer_hotspots` for a direct `is_hotspot` boolean plus tumor counts from the Chang et al. hotspot database (e.g., BRAF V600E: `is_hotspot: true`, 897 tumors as a single-residue hotspot, 545 as a 3D-cluster hotspot). A mutation seen in hundreds of independent tumors is almost certainly a driver. A unique, never-before-seen missense in the same gene is less certain.
- **What is the predicted functional impact?** Truncating mutations (nonsense, frameshift) in tumor suppressors are likely loss-of-function drivers. Missense mutations in oncogenes at known hotspot residues are likely gain-of-function drivers.
- **For unique (non-hotspot) missense in driver genes, look at mechanism, not just pathogenicity.** AlphaMissense gives a score; the ESMC-6B SAE composite `ESM_explain_variant_mechanism(sequence=wt_protein_seq, position=..., ref_aa=..., alt_aa=..., top_k_features=5)` answers *how* the substitution disrupts function — catalytic / ligand-binding / PTM / structural-stability loss. A unique missense that disrupts the same SAE feature category as a known driver hotspot in the same gene is more likely a driver than a missense that disrupts unrelated features. Requires `ESM_API_KEY`; missense only.
- **Conclusion pattern**: A recurrent mutation in a known driver gene is likely actionable. A unique mutation in a gene not associated with cancer is likely a passenger. State your assessment and the reasoning behind it.

### Actionability Reasoning

Actionable means a therapy exists that targets this alteration. Think in tiers based on evidence strength:

- **Tier 1**: FDA-approved drug for this mutation in this cancer type. The standard of care — recommend confidently. Example reasoning: "CIViC returns Level A evidence, FDA label confirms indication."
- **Tier 2**: FDA-approved for this mutation in a different cancer type, or strong clinical trial evidence (phase 2-3) in this cancer type. Reasonable to consider, especially under tumor-agnostic approvals or with molecular tumor board discussion.
- **Tier 3**: Preclinical evidence only — cell line data, animal models, or case reports. May justify clinical trial enrollment but not off-label use.
- **Tier 4**: Biological rationale but no direct evidence — the mutation is in a druggable pathway, or a structurally similar mutation responds to therapy. Hypothesis-generating only.

When synthesizing, state the tier and explain WHY you assigned it based on the evidence you found, not just which database returned a hit.

### Resistance Reasoning

If the patient has already been treated, ask: could this mutation be a resistance mechanism?

- **On-target resistance**: Mutations in the drug target gene itself that restore signaling despite drug binding. These typically emerge at the drug-binding site (e.g., EGFR T790M after erlotinib, EGFR C797S after osimertinib, ABL T315I after imatinib).
- **Bypass pathway activation**: Mutations in parallel signaling pathways that render the target irrelevant (e.g., MET amplification bypassing EGFR inhibition, BRAF activation bypassing MEK inhibition).
- **Phenotypic transformation**: Lineage changes (e.g., small cell transformation in EGFR-mutant lung cancer) that eliminate dependence on the original driver.
- **Timing matters**: If the mutation was detected AFTER treatment, it is more likely a resistance mechanism than if it was present at diagnosis.

### When to Use Which Tool

Form your clinical hypothesis FIRST based on gene function and mutation type, THEN use tools to validate:

- **CIViC** (`civic_search_genes`, `civic_get_variants_by_gene`): Your primary source for clinical evidence. Returns curated evidence items with evidence levels, clinical significance, and associated therapies. Start here for any variant with potential clinical relevance.
- **cBioPortal** (`cBioPortal_get_mutations`): Use to assess mutation prevalence — is this a hotspot? How common is it across cancer types? This informs your driver vs passenger assessment.
- **OpenTargets** (`OpenTargets_get_associated_drugs_by_target_ensemblID`): Use for actionability — what drugs target this gene? Cross-reference with CIViC evidence to assign tiers.
- **PubMed** (`PubMed_search_articles`): Use when CIViC lacks entries for your variant, or to find resistance mechanism reports and recent clinical trial results.
- **ClinicalTrials.gov** (`search_clinical_trials`): Use after establishing the variant is potentially actionable, to find enrollment opportunities.

---

## Tool Reference (Verified Parameters)

### Gene Resolution

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `MyGene_query_genes` | `query`, `species` | `hits[].ensembl.gene`, `.entrezgene`, `.symbol` |
| `UniProt_search` | `query`, `organism`, `limit` | `results[].accession` |
| `OpenTargets_get_target_id_description_by_name` | `targetName` | `data.search.hits[].id` |
| `ensembl_lookup_gene` | `gene_id`, `species` (REQUIRED) | `data.id`, `.version` |

### Clinical Evidence

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `civic_search_genes` | `query`, `limit` | `data.genes.nodes[].id`, `.entrezId` |
| `civic_get_variants_by_gene` | `gene_id` (CIViC numeric) | `data.gene.variants.nodes[]` |
| `civic_get_variant` | `variant_id` | `data.variant` |

### Drug Information

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `OpenTargets_get_associated_drugs_by_target_ensemblID` | `ensemblId`, `size` | `data.target.drugAndClinicalCandidates.rows[]` |
| `FDA_get_indications_by_drug_name` | `drug_name`, `limit` | `results[].indications_and_usage` |
| `drugbank_get_drug_basic_info_by_drug_name_or_id` | `query`, `case_sensitive`, `exact_match`, `limit` (ALL required) | `results[]` |

### Mutation Prevalence

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `cBioPortal_get_mutations` | `study_id`, `gene_list` | `data[].proteinChange` |
| `cBioPortal_get_cancer_studies` | `limit` | `[].studyId`, `.cancerTypeId` |

### Clinical Trials & Literature

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `search_clinical_trials` | `query_term` (required), `condition` | `studies[]` |
| `PubMed_search_articles` | `query`, `limit`, `include_abstract` | Returns **list** of dicts (NOT wrapped) |
| `Reactome_map_uniprot_to_pathways` | `id` (UniProt accession) | Pathway mappings |
| `GTEx_get_median_gene_expression` | `gencode_id`, `operation="median"` | Expression by tissue |

### Variant Annotation & Cancer Hotspots (Genome Nexus)

Complements CIViC/cBioPortal with structured, computed consequence prediction (VEP/SIFT/PolyPhen/AlphaMissense) plus a dedicated cancer-hotspot lookup — use it to establish *in silico* pathogenicity and hotspot status before or alongside the curated clinical-evidence search, not instead of it. Requires **GRCh37/hg19** coordinates (convert first if you only have GRCh38, e.g. via NCBI Variation Services in `tooluniverse-variant-analysis`).

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `GenomeNexus_annotate_variant` | `hgvsg` (GRCh37, e.g. `"7:g.140453136A>T"`) | `most_severe_consequence`, `transcript_consequences[].{hgvsp, sift_prediction, polyphen_prediction, alphaMissense}`, `hotspots.annotation`, `colocated_variants[].dbSnpId` |
| `GenomeNexus_annotate_mutation` | `chromosome`, `start`, `end`, `reference_allele`, `variant_allele` (GRCh37) | Same shape as `annotate_variant` — use when you have separate coordinate fields instead of an HGVS string |
| `GenomeNexus_annotate_dbsnp` | `rsid` (e.g. `"rs121913529"`) | Same shape; resolves the rsID to coordinates first |
| `GenomeNexus_get_cancer_hotspots` | `hgvsg` (GRCh37) | `is_hotspot` (bool), `hotspots[].{residue, tumorCount, type}` — `type` is `"single residue"` or `"3d"` (structural cluster) |
| `GenomeNexus_get_canonical_transcript` | `gene_symbol` | `transcriptId`, `proteinId`, `proteinLength`, `refseqMrnaId`, `pfamDomains[]` |

### Cancer Driver Gene Classification (IntOGen)

Genome Nexus's `is_hotspot` (above) answers "is this exact *variant* recurrent?" IntOGen answers a different, gene-level question: "is this whole *gene* a statistically established cancer driver in this cancer type?", derived from applying 7 independent driver-detection methods (dNdScv, OncodriveFML, OncodriveCLUSTL, HotMAPS, smRegions, CBaSE, MutPanning) to thousands of tumors across 271 cohorts (TCGA, ICGC, Hartwig, and others). Use it to establish gene-level driver status BEFORE or ALONGSIDE the hotspot check — a variant in a gene that isn't a driver in this cancer type is far less likely to be actionable regardless of its hotspot status, and a gene that IS a driver but where your specific variant ISN'T a known hotspot may still warrant the mechanism-based reasoning in "Driver vs Passenger Reasoning" above.

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `IntOGen_list_cancer_types` | none | `data.cancer_types[].{cancer_type_id, cancer_name}` (87 codes, e.g. `BRCA`, `LUAD`, `SKCM`) |
| `IntOGen_get_drivers` | `cancer_type` (IntOGen code, REQUIRED) | `data.driver_genes[].{gene, mutations, samples, cohorts}` |
| `IntOGen_get_gene_info` | `gene` (HUGO symbol, REQUIRED) | `data.cancer_types[].{cancer_type, cancer_name, methods[], mutated_samples, total_samples}` |
| `IntOGen_list_cohorts` | `cancer_type` (optional filter) | `data.cohorts[].{cohort_id, name, samples, source, tumor_type, age_group}` |

**Combined workflow**: given gene + cancer type, call `IntOGen_get_drivers(cancer_type=...)` and check whether the gene appears in `driver_genes[]` — if yes, it's a statistically established driver in this exact cancer type (report `mutations`/`samples`/`cohorts` as supporting evidence). For the inverse question ("which cancer types is this gene a driver in overall?"), use `IntOGen_get_gene_info(gene=...)` instead, which also reports which of the 7 detection `methods` flagged it per cancer type — a gene flagged by multiple independent methods is stronger evidence than one flagged by a single method. **Operational note**: the IntOGen backend is occasionally slow and can time out (~45s) on a cold request — retry once before reporting "no data found."

### Somatic Classification Tiers (CancerVar)

Everything above (Genome Nexus, IntOGen, CIViC, cBioPortal) is evidence you assemble and weigh yourself. `CancerVar_classify_variant` instead runs the full AMP/ASCO/CAP 2017 rubric server-side and returns a ready-made Tier I-IV verdict — use it as a fast, automatable cross-check on your own manual assessment, not as a replacement for citing the underlying evidence above in a report.

| Tool | Key Parameters | Response Key Fields |
|------|---------------|-------------------|
| `CancerVar_classify_variant` | `chrom`, `pos`, `ref`, `alt` (GRCh37/hg19 by default; pass `build="hg38"` for GRCh38), all REQUIRED | `data.tier` (`Tier_I_strong`\|`Tier_II_potential`\|`Tier_III_unknown`\|`Tier_IV_benign`), `data.opai` (Oncogenicity Pathogenicity Index, 0-1), `data.cbp_criteria` (12 named evidence scores, e.g. hotspot-database membership, FDA-approved-therapy association, population rarity) |

Verified live on BRAF V600E (`chrom="7", pos=140453136, ref="A", alt="T", build="hg19"`): `tier="Tier_I_strong"`, `opai=0.99` — matches the FDA-approved-therapy-association tier this variant is known for, and matches the tool's own documented worked example exactly (unlike InterVar below, this example was accurate). Tier I requires CBP_1 or CBP_2 (FDA-approved association) to be active; Tier II is investigational/preclinical evidence without regulatory approval; Tier III is a true VUS-equivalent; Tier IV is benign. Report the tier alongside which specific `cbp_criteria` were active, the same way you'd cite ACMG criteria for a germline call — a bare tier number without its supporting criteria is not an audit-ready answer.

---

## Fallback Strategy

When a primary tool returns no results, fall back rather than reporting "no data found":
- **CIViC empty** -> search PubMed for "[gene] [variant] clinical evidence"
- **OpenTargets no drugs** -> try ChEMBL drug search by target
- **cBioPortal specific study empty** -> try pan-cancer study (msk_impact_2017 or similar)
- **Reactome no pathways** -> use UniProt function annotation for pathway context