tooluniverse-immunology

What this skill does

# Immunology Research Skill

**KEY PRINCIPLES**: Multi-layer evidence; source every claim; use immunology-specific databases first (IEDB, IMGT, SAbDab); always use English gene/protein names in tool calls.

---

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

**For MC about immune mechanisms**: Look up the specific pathway/receptor/cytokine before answering. Use `PubMed_search_articles` with the exact terms from the question. The answer is almost always in the first few search results.

**Specific LOOK UP targets** (never guess these):
- **Immune cell markers**: CD markers for cell subsets (e.g., Treg = CD4+CD25+FOXP3+, not just "CD4+"). Query UniProt or IEDB.
- **Cytokine functions**: IL-17 is pro-inflammatory (Th17), IL-10 is anti-inflammatory (Treg) — but context matters. Verify via KEGG pathway or PubMed.
- **MHC/HLA restrictions**: Which HLA allele presents which peptide — always check IEDB MHC binding data; allele-level differences are critical (HLA-A*02:01 vs HLA-A*02:07 have different peptide repertoires).
- **Antibody Kd values**: Never estimate binding affinity; check SAbDab, IEDB, or published literature.

---

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

## Reasoning Frameworks

**Immune response reasoning** — Every immune response has innate → adaptive phases. Ask: which arm is relevant to the question? Innate (neutrophils, macrophages, complement, pattern recognition) or adaptive (T cells, B cells, antibodies, memory)? Innate is fast (hours) and antigen-nonspecific; adaptive is slow (days) but specific and generates memory. The transition occurs when APCs present antigen to naive T/B cells. Targeting innate suppresses broad inflammation; targeting adaptive disrupts antigen-specific responses. This determines which databases and tools are most relevant.

**Antibody analysis reasoning** — Structure determines function. The variable region (VH/VL, CDR loops) determines antigen specificity. The Fc region determines effector function: complement activation (IgM, IgG), ADCC via FcγR (IgG), or opsonization. When analyzing antibody data, always ask: are we studying binding (Fab — use IEDB, SAbDab, IMGT) or function (Fc — use FAERS for clinical safety, OpenTargets for target biology, TheraSAbDab for therapeutic format/isotype)? Isotype switching changes effector function without changing specificity.

**Autoimmunity reasoning** — Autoimmunity = loss of self-tolerance. Ask: is the attack cell-mediated (T cells destroying tissue → Type 1 diabetes, MS) or antibody-mediated (autoantibodies → SLE, myasthenia gravis, Graves')? Cell-mediated disease implicates MHC class I/II and TCR repertoire; antibody-mediated implicates B cell activation, affinity maturation, and complement. This determines the disease mechanism, the relevant genetic loci (HLA alleles dominate both, but TCR genes matter more for T-cell diseases), and the therapeutic approach (biologics targeting T cells vs. B cells vs. complement).

**Antibody-antigen interaction reasoning** — Binding strength has two axes: affinity (Kd of single binding site, typically nM–pM for therapeutic mAbs) and avidity (combined strength of all binding sites — IgM pentamer has low affinity but high avidity). When analyzing binding data: Kd < 1 nM = very high affinity; 1–100 nM = moderate; > 100 nM = weak. Epitope mapping strategy depends on the question: linear epitopes → peptide arrays or IEDB linear epitope search; conformational epitopes → HDX-MS, cryo-EM, or cross-linking MS. For therapeutic antibodies, check SAbDab for co-crystal structures and TheraSAbDab for clinical-stage format/engineering details.

**Immune signaling cascade reasoning** — When asked "what happens when cytokine X activates cell Y", trace the full pathway: receptor (which subunits?) → proximal kinase (JAK1/2/3, TYK2, Src family?) → transcription factor (STAT1/3/4/5/6, NF-kB, NFAT?) → effector genes (cytokines, cytotoxic molecules, survival factors). Example: IL-12 + T cell → IL-12R (IL12RB1+IL12RB2) → JAK2/TYK2 → STAT4 → IFN-gamma production (Th1 differentiation). Use KEGG pathway hsa04630 (JAK-STAT) and Reactome R-HSA-1280215 (Cytokine Signaling) to verify. Key signaling modules: JAK-STAT (most cytokines), NF-kB (TNF, TLRs, TCR/BCR co-stimulation), MAPK/ERK (growth factors, TCR), PI3K-AKT (co-stimulation, survival).

**Complement system reasoning** — Three activation pathways converge on C3 convertase: Classical (C1q binds antibody-antigen complexes — IgM or IgG → C4b2a), Lectin (MBL binds mannose on pathogens → C4b2a), Alternative (spontaneous C3 hydrolysis + factor B/D → C3bBb, amplification loop). All converge on C5 convertase → MAC (C5b-9). When to check which: suspected immune complex disease (SLE) → classical pathway (C1q, C4); recurrent bacterial infections → alternative or lectin (factor B, MBL); paroxysmal nocturnal hemoglobinuria → terminal pathway (CD55/CD59 deficiency). Therapeutic targets: eculizumab blocks C5; avacopan blocks C5aR.

**Evidence grading** — A (strong): GWAS p < 5e-8 + functional data + clinical signal. B (moderate): genetics or pathway evidence, limited functional data. C (preliminary): single-database hit only. Converging genetic (GWAS/Orphanet) + protein interaction (IntAct/BioGRID) + pathway data raises confidence. FAERS PRR > 2 with IC025 > 0 is a signal, not causal proof. TIMER2 deconvolution estimates require orthogonal validation.

---

## Tool Reference

### Antibody / Structural (SAbDab, TheraSAbDab)

| Tool | Key Parameters |
|------|---------------|
| `SAbDab_get_structure` | `pdb_id` (str) — structure details and chain info |
| `SAbDab_get_summary` | `pdb_id` (str) — CDR and chain summary |
| `SAbDab_search_structures` | `query` (str) — returns browse URL only, not JSON |
| `TheraSAbDab_search_therapeutics` | `query` (str, e.g. "pembrolizumab") — INN, target, format, phase |
| `TheraSAbDab_search_by_target` | `target` (str) — all therapeutics for an antigen |
| `TheraSAbDab_get_all_therapeutics` | (none) — full therapeutic antibody list |

### Epitope and Immune Assays (IEDB)

All search tools accept `limit`, `offset`, `filters` (PostgREST dict).

| Tool | Extra Parameters |
|------|-----------------|
| `iedb_search_epitopes` | `sequence_contains`, `structure_type` |
| `iedb_search_tcell_assays` | `sequence_contains`, `mhc_class`, `qualitative_measure` |
| `iedb_search_bcell` | filters only |
| `iedb_search_mhc` | filters only |
| `iedb_search_tcr_sequences` / `iedb_search_bcr_sequences` | filters only |

Detail tools by `structure_id`: `iedb_get_epitope_antigens`, `iedb_get_epitope_mhc`, `iedb_get_epitope_tcell_assays`, `iedb_get_epitope_references`.

### Immunoglobulin Genes (IMGT)

`IMGT_search_genes`, `IMGT_get_gene_info`, `IMGT_get_sequence` — all take `gene_name` (e.g. "IGHV1-2").

### Protein Interactions (IntAct, BioGRID)

| Tool | Key Parameters |
|------|---------------|
| `intact_get_interaction_network` | `identifier` (UniProt accession — gene symbols return 0 results), `limit` |
| `intact_search_interactions` | `query` (keyword), `limit` |
| `BioGRID_get_interactions` | `gene_names` (list), `organism` ("9606" string), `limit` |
| `BioGRID_get_chemical_interactions` | `gene_names` (list), `chemical_names` (list), `organism` (int) |

Weight interaction evidence: co-IP and two-hybrid = direct; co-expression or text-mining = hypothesis-generating.

### Cytokine / Signaling (OpenTargets, GWAS)

| Tool | Key Parameters |
|------|---------------|
| `OpenTargets_get_target_id_description_by_name` | `targetName` — resolves g