/by-database

id: "skill_7b1465f73e1a4c5c9cd7591d123dac91"
name: "by-database"
display-name: "BY Database Queries (PDB / UniProt / SAbDab)"
short-description: "Query the BY MCP database servers (PDB, UniProt, SAbDab) for target characterization, antibody scaffold selection, and competition analysis. Use when you need structural metadata, sequence/domain annotations, or known antibody-antigen complexes for a target."
category: "research"
keywords: "PDB, RCSB, UniProt, SAbDab, antibody database, structure lookup, interface residues, CDR sequences, hotspot, scaffold selection"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools: [
  "mcp__by-pdb__pdb_search",
  "mcp__by-pdb__pdb_fetch_structure",
  "mcp__by-pdb__pdb_get_chains",
  "mcp__by-pdb__pdb_interface_residues",
  "mcp__by-pdb__pdb_download",
  "mcp__by-uniprot__uniprot_search",
  "mcp__by-uniprot__uniprot_fetch_protein",
  "mcp__by-uniprot__uniprot_get_domains",
  "mcp__by-uniprot__uniprot_get_variants",
  "mcp__by-sabdab__sabdab_search_antibodies",
  "mcp__by-sabdab__sabdab_get_structure",
  "mcp__by-sabdab__sabdab_cdr_sequences",
  "mcp__by-sabdab__sabdab_search_by_antigen"
]

Skill: by-database

Use the BY MCP database tools to query PDB, UniProt, and SAbDab for target characterization, antibody scaffold selection, and competition analysis.

---

When to Use This Skill

Use this skill when you need:

• ✅ Structural metadata for a target (resolution, method, organism, chains)
• ✅ Interface residue lists for hotspot selection in PXDesign / BoltzGen
• ✅ Canonical UniProt sequence, domain boundaries, or known variants
• ✅ Existing antibody-antigen complexes for scaffold selection or competition analysis
• ✅ Cross-referencing PDB residue numbering with UniProt positions
• ✅ Verifying chain composition before generating a design spec

**Don't use this skill for:**

• ❌ Full target research narrative or literature review → use `by-research`
• ❌ Epitope hotspot scoring or surface analysis → use `by-epitope-analysis`
• ❌ Scoring designs (ipSAE, ipTM, liabilities) → use `by-scoring` / `by-screening`
• ❌ Web search or PubMed lookups → fall back to PubMed/bioRxiv tools then WebSearch
• ❌ Submitting compute jobs → use `boltzgen`, `pxdesign`, `protenix` skills

---

Quick Start

Look up a target end-to-end in three calls:

mcp__by-pdb__pdb_search(query="PD-L1", max_results=10)
mcp__by-uniprot__uniprot_search(query="CD274 human", max_results=5)
mcp__by-sabdab__sabdab_search_by_antigen(antigen_name="PD-L1", max_results=20)

For batch enrichment of a known list of PDB IDs without an MCP loop:

python scripts/batch_pdb_lookup.py --ids 7S4S 6XWG 5JDS --out enriched.csv

✅ **VERIFICATION:** Expect `✓ batch_pdb_lookup completed: 3 rows -> enriched.csv`.

---

Inputs

**Required (at least one of):**

• **PDB ID** — 4-character RCSB identifier (e.g. `7S4S`). Source: `mcp__by-pdb__pdb_search`.
• **UniProt accession** — e.g. `Q9NZQ7`. Source: `mcp__by-uniprot__uniprot_search`.
• **Target name / gene symbol** — e.g. `"PD-L1"`, `"CD274"`. Used as free-text query.
• **Antigen name** — for SAbDab antibody lookups (e.g. `"HER2"`).

**Optional:**

• **Chain IDs** — author chain IDs from `mcp__by-pdb__pdb_get_chains` (e.g. `A`, `H`, `L`).
• **Distance cutoff** — Angstroms for interface analysis (default 5.0; 4.0 strict, 6.0 extended).
• **Species filter** — for SAbDab queries (e.g. `"HOMO SAPIENS"`).
• **Output directory** — for `mcp__by-pdb__pdb_download`.

See [references/pdb-quality-metrics.md](references/pdb-quality-metrics.md) for resolution and completeness thresholds.

---

Outputs

All MCP tools return JSON strings. Parse before display — never show raw JSON to the user.

**PDB tool outputs:**

• `pdb_search` → list of `{pdb_id, title, method, resolution, release_date}`.
• `pdb_fetch_structure` → object with `polymer_entity_count`, `organism`, plus the search fields.
• `pdb_get_chains` → list of `{chain_id, entity_id, molecule_name, sequence, length}`.
• `pdb_interface_residues` → `{chain1_residues:[{resname,resseq}], chain2_residues:[...], contact_count}`.
• `pdb_download` → `{path, size_bytes}`. Files are CIF (preferred) or PDB.

**UniProt tool outputs:**

• `uniprot_search` → list of `{accession, name, organism, gene_name, length, reviewed}`.
• `uniprot_fetch_protein` → full record incl. `sequence`, `function_description`, `subcellular_location`.
• `uniprot_get_domains` → list of `{type, description, start, end}`.
• `uniprot_get_variants` → list of `{type, position, original, variation, description}`.

**SAbDab tool outputs:**

• `sabdab_search_antibodies` / `sabdab_search_by_antigen` → list of antibody PDB records.
• `sabdab_get_structure` → detailed record incl. `r_free`, `cdr_lengths`, `chain_pairings`.
• `sabdab_cdr_sequences` → `{H1, H2, H3, L1, L2, L3}` with `{sequence, length}` each.

**Script outputs (this skill's `scripts/`):**

• `batch_pdb_lookup.py` → CSV with one row per PDB ID (resolution, organism, chain count, ligands).
• `find_similar_targets.py` → CSV with related UniProt/PDB entries ranked by % sequence identity.

---

Clarification Questions

**⚠️ CRITICAL: ASK THIS FIRST.** Confirm the user actually has identifiers in hand.

1. **Identifiers** (ASK THIS FIRST):

• Do you have a PDB ID, UniProt accession, gene symbol, or just a target name?
• If only a target name, we will start with `mcp__by-pdb__pdb_search` and

`mcp__by-uniprot__uniprot_search` to resolve canonical IDs.

2. **Organism:**

• Human, mouse, viral, other?
• Determines which UniProt entry is canonical and which PDB structures are relevant.

3. **Modality intent (drives SAbDab usage):**

• Antibody (Fab/IgG), nanobody (VHH), or non-antibody binder?
• Nanobody designs need templates with `light_chain = ""`. Fabs need both H and L.

4. **Resolution threshold:**

• Default ≤2.5 Å for X-ray. Cryo-EM may go to 3.0–3.5 Å.
• Lower the bar for novel targets where nothing better exists.

5. **Bound vs apo state:**