001tmf/blatant-why/by-database

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

1. Organism:

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

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

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

1. Bound vs apo state:

• For interface analysis you need holo (bound) structures.
• Apo structures are fine for general topology but miss the binding interface.

1. Downstream tool:

• PXDesign (de novo binder), BoltzGen (antibody/nanobody), or Protenix (refold only)?
• This affects which fields you must extract (e.g. hotspot range notation vs. CDR lengths).

1. Cross-reference need:

• Do you need PDB→UniProt numbering reconciliation?
• Required when reporting hotspot positions across data sources.

Standard Workflow

🚨 MANDATORY: USE MCP TOOLS AS THE PRIMARY DATA PATH 🚨

Do not WebSearch for data that exists in PDB, UniProt, or SAbDab. Batch your MCP calls and present one consolidated summary — never expose raw JSON.

Target Characterization (PDB-first)

1. mcp__by-pdb__pdb_search(query="<target>") — find available structures.
2. mcp__by-pdb__pdb_fetch_structure(pdb_id="<top>") — compare resolution + method.
3. mcp__by-pdb__pdb_get_chains(pdb_id="<top>") — identify target chain vs. binder vs. ligands.
4. mcp__by-uniprot__uniprot_search(query="<gene> <organism>") then

mcp__by-uniprot__uniprot_fetch_protein — sequence, function, location.

1. mcp__by-uniprot__uniprot_get_domains(accession=...) — domain boundaries.
2. mcp__by-pdb__pdb_interface_residues(pdb_id=..., chain1=..., chain2=...) — epitope residues.
3. mcp__by-uniprot__uniprot_get_variants(accession=...) — flag polymorphic hotspots.
4. mcp__by-pdb__pdb_download(pdb_id=..., format="cif") — local file for BY design tools.

Antibody Scaffold Selection (SAbDab-first)

1. mcp__by-sabdab__sabdab_search_by_antigen(antigen_name="<target>") — known antibodies.
2. mcp__by-sabdab__sabdab_get_structure(pdb_id="<top>") — resolution, species, subclass, CDR lengths.
3. mcp__by-sabdab__sabdab_cdr_sequences(pdb_id="<top>") — CDR architectures.
4. Match CDRH3 length to target depth (10–15 standard, 15–20+ deep pockets, 8–10 flat).
5. Pick a high-resolution human (or humanized) scaffold.
6. mcp__by-pdb__pdb_fetch_structure(pdb_id="<scaffold>") — final quality check.

Competition Analysis

1. mcp__by-sabdab__sabdab_search_by_antigen — all known antibodies.
2. mcp__by-pdb__pdb_search — non-antibody binders too.
3. mcp__by-pdb__pdb_interface_residues on each competitor — map epitopes.
4. Compare interface residues across binders → conserved hotspots vs. novel epitope opportunities.
5. mcp__by-uniprot__uniprot_get_variants — does any escape mutation hit competitor sites?

Batch Lookups (use scripts)

For >5 PDB IDs or >5 UniProt accessions, prefer the scripts in this skill — they deduplicate, retry on transient errors, and emit a single CSV instead of N JSON blobs:

python scripts/batch_pdb_lookup.py --ids 7S4S 6XWG 5JDS 4HHB --out targets.csv
python scripts/find_similar_targets.py --uniprot P01375 --max-hits 25 --out homologs.csv

✅ VERIFICATION: Each script prints ✓ <name> completed: N rows -> <path>.

When Scripts Fail

Hierarchy (apply in order):

1. Fix and retry (90%) — Install missing dep (pip install httpx biopython),

then re-run with the same args.

1. Modify script (5%) — Edit the local script file (e.g. tighten resolution

filter, change e-value threshold for BLAST).

1. Use as reference (4%) — Read the script and call the MCP tools manually

for one-off cases.

1. Write from scratch (1%) — Only if the underlying RCSB / UniProt / SAbDab

API has changed in a way that breaks the script. Document why.

Decision tree:

• HTTP 429 / rate limit → step 1 (the script retries with backoff; re-run).
• Missing httpx / biopython → step 1 (pip install).
• Wrong output columns → step 2 (modify script).
• Tool unavailable in environment → step 3 (MCP fallback).
• API schema changed upstream → step 4 (rewrite + report).

Decision Points

When to prefer X-ray vs. cryo-EM

See references/pdb-quality-metrics.md. Short form: X-ray ≤2.5 Å for interface work; cryo-EM acceptable to ~3.0 Å for large complexes where X-ray is impossible.

Holo vs. apo selection

For interface residues you MUST use a holo (bound) structure. Apo can confirm domain architecture but contact residues will be missing or rearranged.

Reviewed vs. unreviewed UniProt

Always prefer reviewed (Swiss-Prot). Unreviewed (TrEMBL) entries may lack domain, variant, and function annotations. See references/uniprot-fields.md.

Antigen-deposited vs. validated SAbDab entries

SAbDab indexes the PDB; presence in SAbDab does NOT mean affinity has been independently validated. See references/sabdab-best-practices.md.

Common Issues