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

---

## 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
**Optional**: Cancer type (improves specificity)

### Accepted Input Formats

| Format | Example | How to Parse |
|--------|---------|-------------|
| Gene + amino acid change | EGFR L858R | gene=EGFR, variant=L858R |
| Gene + HGVS protein | BRAF p.V600E | gene=BRAF, variant=V600E |
| Gene + exon notation | EGFR exon 19 deletion | gene=EGFR, variant=exon 19 deletion |
| Gene + fusion | EML4-ALK fusion | gene=ALK, variant=EML4-ALK |
| Gene + amplification | HER2 amplification | gene=ERBB2, variant=amplification |

### Gene Symbol Normalization

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`.

---

## Evidence Grading Summary

| Tier | Criteria | Examples |
|------|----------|---------|
| **T1** | FDA-approved therapy, Level A CIViC evidence, phase 3 trial | Osimertinib for EGFR T790M |
| **T2** | Phase 2/3 clinical data, Level B CIViC evidence | Combination trial data |
| **T3** | Preclinical data, Level D CIViC, case reports | Novel mechanisms, in vitro |
| **T4** | Computational prediction, pathway inference | Docking, pathway analysis |

## Clinical Actionability Scoring

| Score | Criteria |
|-------|----------|
| **HIGH** | FDA-approved targeted therapy for this exact mutation + cancer type |
| **MODERATE** | Approved therapy for different cancer type with same mutation, OR phase 2-3 trial data |
| **LOW** | Only preclinical evidence or pathway-based rationale |
| **UNKNOWN** | Insufficient data to assess actionability |

For full scoring tables and treatment prioritization, see `SCORING_TABLES.md`.

---

## 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.knownDrugs.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 |

For full tool parameter reference, see `TOOLS_REFERENCE.md`.

---

## Fallback Chains

| Primary Tool | Fallback | Use When |
|-------------|----------|----------|
| CIViC variant lookup | PubMed literature search | Gene not found in CIViC |
| OpenTargets drugs | ChEMBL drug search | No OpenTargets drug hits |
| FDA indications | DrugBank drug info | Drug not in FDA database |
| cBioPortal TCGA study | cBioPortal pan-cancer | Specific cancer study not available |
| GTEx expression | Ensembl gene lookup | GTEx returns empty |
| Reactome pathways | UniProt function | Pathway mapping fails |

---

## Quantified Minimums

| Section | Requirement |
|---------|-------------|
| Gene IDs | At least Ensembl + UniProt resolved |
| Clinical evidence | CIViC queried + PubMed literature search |
| Mutation prevalence | At least 1 cBioPortal study |
| Therapeutic options | All approved drugs listed + FDA label for top drugs |
| Resistance | Literature search + known patterns documented |
| Clinical trials | At least 1 search query executed |
| Prognostic impact | PubMed literature search performed |
| Pathway context | Reactome pathway mapping attempted |

---

## See Also

- `ANALYSIS_DETAILS.md` - Detailed code snippets and API call patterns for each phase
- `REPORT_TEMPLATE.md` - Full report template with completeness checklist
- `SCORING_TABLES.md` - Evidence grading, treatment prioritization, use cases
- `TOOLS_REFERENCE.md` - Detailed tool parameter reference
- `QUICK_START.md` - Example usage and quick reference
- `EXAMPLES.md` - Complete example reports