tooluniverse-protein-structure-retrieval

Protein Structure Data Retrieval

Retrieve protein structures with proper disambiguation, quality assessment, and comprehensive metadata.

IMPORTANT: Always use English terms in tool calls (protein names, organism names), even if the user writes in another language. Only try original-language terms as a fallback if English returns no results. Respond in the user's language.

Workflow Overview

Phase 0: Clarify (if needed)
    ↓
Phase 1: Disambiguate Protein Identity
    ↓
Phase 2: Retrieve Structures (Internal)
    ↓
Phase 3: Report Structure Profile

---

Phase 0: Clarification (When Needed)

Ask the user ONLY if:

• Protein name matches multiple genes/families (e.g., "kinase" → which kinase?)
• Organism not specified for conserved proteins
• Intent unclear: need experimental structure vs AlphaFold prediction?

Skip clarification for:

• Specific PDB IDs (4-character codes)
• UniProt accessions
• Unambiguous protein names with organism

---

Phase 1: Protein Disambiguation

1.1 Resolve Protein Identity

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

# Strategy depends on input type
if user_provided_pdb_id:
    # Direct structure retrieval
    pdb_id = user_provided_pdb_id.upper()
    
elif user_provided_uniprot:
    # Get UniProt info, then search structures
    uniprot_id = user_provided_uniprot
    # Can also get AlphaFold structure
    af_structure = tu.tools.alphafold_get_structure_by_uniprot(
        uniprot_id=uniprot_id
    )
    
elif user_provided_protein_name:
    # Search by name
    result = tu.tools.search_structures_by_protein_name(
        protein_name=protein_name
    )

1.2 Identity Resolution Checklist

• [ ] Protein name/gene identified
• [ ] Organism confirmed
• [ ] UniProt accession (if available)
• [ ] Isoform/variant specified (if relevant)

1.3 Handle Naming Collisions

Common ambiguous terms:

| Term | Ambiguity | Resolution |

|------|-----------|------------|

| "kinase" | Hundreds of kinases | Ask which kinase (EGFR, CDK2, etc.) |

| "receptor" | Many receptor types | Specify receptor family |

| "protease" | Multiple families | Ask serine/cysteine/metallo/etc. |

| "hemoglobin" | Clear | Proceed (α/β chain specified if needed) |

| "insulin" | Clear | Proceed |

---

Phase 2: Data Retrieval (Internal)

Retrieve all data silently. Do NOT narrate the search process.

2.1 Search Structures

# Search by protein name
result = tu.tools.search_structures_by_protein_name(
    protein_name=protein_name
)

# Filter results by quality
high_res = [
    entry for entry in result["data"]
    if entry.get("resolution") and entry["resolution"] < 2.5
]

2.2 Get Structure Details

For each relevant structure:

pdb_id = "4INS"

# Basic metadata
metadata = tu.tools.get_protein_metadata_by_pdb_id(pdb_id=pdb_id)

# Experimental details
exp_details = tu.tools.get_protein_experimental_details_by_pdb_id(
    pdb_id=pdb_id
)

# Resolution (if X-ray)
resolution = tu.tools.get_protein_resolution_by_pdb_id(pdb_id=pdb_id)

# Bound ligands
ligands = tu.tools.get_protein_ligands_by_pdb_id(pdb_id=pdb_id)

# Similar structures
similar = tu.tools.get_similar_structures_by_pdb_id(
    pdb_id=pdb_id,
    cutoff=2.0
)

2.3 PDBe Additional Data

# Entry summary
summary = tu.tools.pdbe_get_entry_summary(pdb_id=pdb_id)

# Molecular entities
molecules = tu.tools.pdbe_get_molecules(pdb_id=pdb_id)

# Binding sites
binding_sites = tu.tools.pdbe_get_binding_sites(pdb_id=pdb_id)

2.4 AlphaFold Predictions

# When no experimental structure exists, or for comparison
if uniprot_id:
    af_structure = tu.tools.alphafold_get_structure_by_uniprot(
        uniprot_id=uniprot_id
    )

Fallback Chains

| Primary | Fallback | Notes |

|---------|----------|-------|

| RCSB search | PDBe search | Regional availability |

| get_protein_metadata | pdbe_get_entry_summary | Alternative source |

| Experimental structure | AlphaFold prediction | No experimental structure |

| get_protein_ligands | pdbe_get_binding_sites | Ligand info unavailable |

---

Phase 3: Report Structure Profile

Output Structure

Present as a Structure Profile Report. Hide search process.

# Protein Structure Profile: [Protein Name]

**Search Summary**
- Query: [protein name/PDB ID]
- Organism: [species]
- Structures Found: [N] experimental, [M] AlphaFold

---

## Best Available Structure

### [PDB ID]: [Title]

| Attribute | Value |
|-----------|-------|
| **PDB ID** | [pdb_id] |
| **UniProt** | [uniprot_id] |
| **Organism** | [species] |
| **Method** | X-ray / Cryo-EM / NMR |
| **Resolution** | [X.XX] Å |
| **Release Date** | [date] |

**Quality Assessment**: ●●● High / ●●○ Medium / ●○○ Low

### Experimental Details
| Parameter | Value |
|-----------|-------|
| **Method** | [X-ray crystallography] |
| **Resolution** | [1.9 Å] |
| **R-factor** | [0.18] |
| **R-free** | [0.21] |
| **Space Group** | [P 21 21 21] |

### Structure Composition
| Component | Count | Details |
|-----------|-------|---------|
| **Chains** | [N] | [A (enzyme), B (inhibitor)] |
| **Residues** | [N] | [coverage %] |
| **Ligands** | [N] | [list ligand names] |
| **Waters** | [N] | |
| **Metals** | [N] | [Zn, Mg, etc.] |

### Bound Ligands
| Ligand ID | Name | Type | Binding Site |
|-----------|------|------|--------------|
| [ATP] | Adenosine triphosphate | Substrate | Active site |
| [MG] | Magnesium ion | Cofactor | Catalytic |

### Binding Site Details
For drug discovery applications:

**Site 1: Active Site**
- Location: Chain A, residues 45-89
- Key residues: Asp45, Glu67, His89
- Pocket volume: [X] ų
- Druggability: High/Medium/Low

---

## Alternative Structures

Ranked by quality and relevance:

| Rank | PDB ID | Resolution | Method | Ligands | Notes |
|------|--------|------------|--------|---------|-------|
| 1 | [4INS] | 1.9 Å | X-ray | Zn | Best resolution |
| 2 | [3I40] | 2.1 Å | X-ray | Zn, phenol | With inhibitor |
| 3 | [1TRZ] | 2.3 Å | X-ray | None | Porcine |

---

## AlphaFold Prediction

### AF-[UniProt]-F1

| Attribute | Value |
|-----------|-------|
| **UniProt** | [uniprot_id] |
| **Model Version** | [v4] |
| **Confidence (pLDDT)** | [average score] |

**Confidence Distribution**:
- Very High (>90): [X]% of residues
- High (70-90): [X]% of residues
- Low (50-70): [X]% of residues
- Very Low (<50): [X]% of residues

**Use Cases**:
- ✓ Overall fold reliable
- ✓ Core domain structure
- ⚠ Loop regions uncertain
- ✗ Not suitable for binding site analysis

---

## Structure Comparison

| Property | [PDB_1] | [PDB_2] | AlphaFold |
|----------|---------|---------|-----------|
| Resolution | 1.9 Å | 2.5 Å | N/A (predicted) |
| Completeness | 98% | 85% | 100% |
| Ligands | Yes | No | No |
| Confidence | Experimental | Experimental | High (85 avg) |

---

## Download Links

### Coordinate Files
| Format | PDB ID | Link |
|--------|--------|------|
| PDB | [4INS] | [link] |
| mmCIF | [4INS] | [link] |
| AlphaFold | [UniProt] | [link] |

### Database Links
- RCSB PDB: https://www.rcsb.org/structure/[pdb_id]
- PDBe: https://www.ebi.ac.uk/pdbe/entry/pdb/[pdb_id]
- AlphaFold: https://alphafold.ebi.ac.uk/entry/[uniprot_id]

Retrieved: [date]

---

Quality Assessment Tiers

Experimental Structures

| Tier | Symbol | Criteria |

|------|--------|----------|

| Excellent | ●●●● | X-ray <1.5Å, complete, R-free <0.22 |

| High | ●●●○ | X-ray <2.0Å OR Cryo-EM <3.0Å |

| Good | ●●○○ | X-ray 2.0-3.0Å OR Cryo-EM 3.0-4.0Å |

| Moderate | ●○○○ | X-ray >3.0Å OR NMR ensemble |

| Low | ○○○○ | >4.0Å, incomplete, or problematic |

Resolution Guide

| Resolution | Use Case |

|------------|----------|

| <1.5 Å | Atomic detail, H-bond analysis |

| 1.5-2.0 Å | Drug design, mechanism studies |

| 2.0-2.5 Å | Structure-based design |

| 2.5-3.5 Å | Overall architecture, fold |

| >3.5 Å | Domain arrangement only |

AlphaFold Confidence

| pLDDT Score | Interpretation |

|-------------|----------------|

| >90 | Very high confidence, experimental-like |

| 70-90 | Good backbone confidence |

| 50-70 | Uncertain, flexible regions |

| <50 | Low confidence, likely disordered |

---

Completeness Checklist

Every structure report MUST include:

For Specific PDB ID (Required)

• [ ] PDB ID and title
• [ ] Experimental method
• [ ] Resolution (or N/A for NMR)
• [ ] Organism
• [ ] Quality assessment
• [ ] Download links

For Protein Name Search (Required)

• [ ] Search summary with result count
• [ ] Top structures with quality ranking
• [ ] Best structure recommendation
• [ ] AlphaFold alternative (if no experimental structure)

Always Include

• [ ] Ligand information (or "No ligands bound")
• [ ] Data sources with links
• [ ] Retrieval date

---

Common Use Cases

Drug Discovery Target

User: "Get structure for EGFR kinase with inhibitor"

→ Filter for ligand-bound structures, emphasize binding site

Model Building

User: "Find best template for homology modeling of protein X"

→ High-resolution structures, note sequence coverage

Structure Comparison

User: "Compare available SARS-CoV-2 main protease structures"

→ All structures with systematic comparison table

AlphaFold When No Experimental

User: "Structure of protein with UniProt P12345"

→ Check PDB first, then AlphaFold, note confidence

---

Error Handling

| Error | Response |

|-------|----------|

| "PDB ID not found" | Verify 4-character format, check if obsoleted |

| "No structures for protein" | Offer AlphaFold prediction, suggest similar proteins |

| "Download failed" | Retry once, provide alternative link |

| "Resolution unavailable" | Likely NMR/model, note in assessment |

---

Tool Reference

RCSB PDB (Experimental Structures)

| Tool | Purpose |

|------|---------|

| search_structures_by_protein_name | Name-based search |

| get_protein_metadata_by_pdb_id | Basic info |

| get_protein_experimental_details_by_pdb_id | Method details |

| get_protein_resolution_by_pdb_id | Quality metric |

| get_protein_ligands_by_pdb_id | Bound molecules |

| download_pdb_structure_file | Coordinate files |

| get_similar_structures_by_pdb_id | Homologs |

PDBe (European PDB)

| Tool | Purpose |

|------|---------|

| pdbe_get_entry_summary | Overview |

| pdbe_get_molecules | Molecular entities |

| pdbe_get_experiment_info | Experimental data |

| pdbe_get_binding_sites | Ligand pockets |

AlphaFold (Predictions)

| Tool | Purpose |

|------|---------|

| alphafold_get_structure_by_uniprot | Get prediction |

| alphafold_search_structures | Search predictions |