Skip to content

Structure-intelligence tools

alphafold_sovereign.tools.structure_intelligence

Structure-intelligence MCP tools.

These tools take raw AlphaFold structures (PDB text and PAE arrays from AlphaFold DB) and derive a small set of summaries from them:

  • pLDDT and PAE confidence summaries, including the positions where near-diagonal PAE is locally elevated. Those positions are not domain boundaries, and no domain count is derived from them,
  • a 64-slot exploratory Cα feature vector that holds at most 16 summary statistics. Optional GUDHI computes H₀/H₁ at the final 15-Å Vietoris-Rips filtration step and contributes eight bar-lifetime statistics for each; H₂ is not computed and the other 48 slots are zero. With GUDHI, models longer than 500 residues are reduced to 500 evenly spaced Cα atoms first. Without GUDHI, the fallback uses every residue: it fills eight slots with distance and contact statistics, one of them the 4-Å contact-graph component count, and computes no persistent homology,
  • a pairwise distance matrix between TDA fingerprints (the implementation is an L2 distance on length-normalised fingerprint vectors — it is not an optimal-transport Wasserstein distance; see _fingerprint_distance),
  • geometric clusters of core residues with an uncalibrated geometry score. This is not a validated binding-pocket detector, and no druggability class is assigned, and
  • an intrinsic-disorder-region map.

All tools are read-only. Tools that require outbound HTTP fail closed when ALPHAFOLD_OFFLINE=1: the client raises AirGapError before a socket is opened. The five tools that take one accession then return retrieval_status: "request_failed", not a missing model. compare_proteins_topologically lists each accession under proteins_failed with the reason instead, and find_evolutionary_structural_shifts queries Ensembl first and lets that client's AirGapError propagate. There is no local structure cache.

Tool inventory
  1. analyze_structural_confidence — pLDDT + PAE confidence summary
  2. compute_topology_fingerprint — Exploratory Cα features; H₀/H₁ if GUDHI
  3. compare_proteins_topologically — Pairwise fingerprint-distance matrix
  4. find_evolutionary_structural_shifts — Cross-species TDA fingerprint compare
  5. score_binding_pocket_geometry — Core-residue clusters + geometry score
  6. detect_intrinsically_disordered — IDR region map
  7. get_protein_structure — Retrieve AF model metadata, URLs, coordinates

POCKET_IDEAL_RESIDUES module-attribute

POCKET_IDEAL_RESIDUES = 12.0

Residue count at/above which the size sub-score saturates.

POCKET_IDEAL_ROG_ANGSTROM module-attribute

POCKET_IDEAL_ROG_ANGSTROM = 5.0

Radius of gyration (Å) scoring peak compactness.

POCKET_ROG_TOLERANCE_ANGSTROM module-attribute

POCKET_ROG_TOLERANCE_ANGSTROM = 5.0

Å of radius-of-gyration deviation that drives the compactness sub-score to 0.

POCKET_CENTROID_OFFSET_SATURATION_ANGSTROM module-attribute

POCKET_CENTROID_OFFSET_SATURATION_ANGSTROM = 20.0

Centroid offset (Å) at/above which the offset sub-score saturates.

The sub-score rises with the cluster's offset from the model centre, so among the core residues it ranks more peripheral clusters higher. This is an uncalibrated prior: it measures neither solvent access nor burial, and it does not indicate ligand binding.

analyze_structural_confidence async

analyze_structural_confidence(params: UniProtInput) -> dict[str, Any]

Analyze AlphaFold structural confidence using pLDDT and PAE.

Returns a structural reliability summary (not a per-residue profile): - pLDDT: the model's mean confidence (AlphaFold DB globalMetricValue) plus a coarse confidence tier - PAE (predicted aligned error): mean and maximum; up to five residue pairs more than 10 positions apart with PAE above 15 Å (one-based model indices); and local_high_pae, the approximate zero-based model indices where a run of locally elevated near-diagonal PAE begins (a short stretch much less certain than the model as a whole, such as a flexible tail or linker) - Domains: NOT assessed. Near-diagonal PAE does not locate domain boundaries; the legacy domain_boundaries block is kept for existing clients with n_putative_domains null and no candidate positions - Druggability pre-screen: model confidence limitations; actual ordered fraction and ligand suitability are NOT assessed

pLDDT interpretation

90: Very high confidence — likely correct at backbone + sidechain level 70–90: High confidence — backbone correct, some sidechain uncertainty 50–70: Low confidence — may be IDP or novel fold < 50: Very low model confidence; does not establish disorder

Input fields

params.uniprot_id: UniProt accession.

compute_topology_fingerprint async

compute_topology_fingerprint(params: UniProtInput) -> dict[str, Any]

Compute an exploratory, rotation-invariant Cα summary vector for an AlphaFold model.

Fetches the AlphaFold model for uniprot_id and derives an exploratory 64-slot feature vector from its Cα coordinates. With GUDHI installed, H0 and H1 are computed on the 15-Å Vietoris-Rips 2-skeleton and the vector holds 16 summary statistics of their finite bar lifetimes (eight each); the other 48 slots are zero. H2 is NOT computed. On this GUDHI path, models longer than 500 residues are reduced to 500 evenly spaced Cα atoms first, so their Betti numbers and statistics describe that subsample (subsampled is then true). Without GUDHI the fallback uses every residue, with no subsampling: the vector holds eight distance and contact statistics, one of them a 4-Å contact-graph component count, and no persistent homology is computed. Betti numbers describe this chosen filtration, not protein domains, β-barrels, drug cavities, molecular function, or an experimental structure.

Returns the fingerprint vector and its slot layout, the Betti numbers, the residue counts, and which method ran. Full persistent homology needs the optional [tda] extra (gudhi); without it a coarse fallback runs that does NOT compute persistent homology, and the result flags this. Returns a no-structure result when AlphaFold DB has no model for the accession. This is a coarse, geometry-only summary — not a substitute for sequence alignment, RMSD, or functional-homology assessment.

Input fields

params.uniprot_id: UniProt accession of the protein to fingerprint, e.g. 'P38398' (BRCA1).

compare_proteins_topologically async

compare_proteins_topologically(params: MultiProteinInput) -> dict[str, Any]

Compare multiple proteins using a TDA-fingerprint distance.

Computes a pairwise distance matrix between the TDA fingerprints of the provided proteins. Distance metric: L2 distance between length-normalised 64-slot fingerprint vectors (see _fingerprint_distance). Distance = 0 means identical fingerprints; larger values mean more divergent fingerprints. This is not a Wasserstein distance between persistence diagrams.

The vectors hold at most 16 statistics (see compute_topology_fingerprint). With GUDHI (the optional [tda] extra), a model longer than 500 residues is compared on 500 evenly spaced Cα atoms. Without GUDHI the fallback uses every residue of every model, with no subsampling, and builds each model's full pairwise distance matrix, so its cost grows with the square of the model length. protein_metadata reports n_residues_used and subsampled for each model. In an internal audit of 23 AlphaFold models run with GUDHI, nearly all of each normalised vector lay in its two total-persistence components, so the distance mostly tracks one ratio: total H1 over total H0 persistence. It has no validated threshold for fold similarity and is not a functional, sequence-similarity or binding-site measure (LIMITATIONS.md L12).

Input fields

params.uniprot_ids: 2–10 UniProt accessions.

find_evolutionary_structural_shifts async

find_evolutionary_structural_shifts(params: EvolutionaryInput) -> dict[str, Any]

Report ortholog sequence identity and exploratory structural distances.

Distances between Cα-derived feature vectors are not calibrated evolutionary, functional, binding, or antibody cross-reactivity measures. The GUDHI and geometric-proxy methods are distinguished in each result. There is deliberately no cross-method conservation ranking.

score_binding_pocket_geometry async

score_binding_pocket_geometry(params: BindingPocketInput) -> dict[str, Any]

Cluster the core residues of an AlphaFold model by geometry.

Not a validated binding-pocket detector; no druggability class is assigned. Cα atoms closer to the model centroid than the 60th percentile of centroid distances are grouped greedily: in sequence order, each unassigned core residue seeds a cluster of the unassigned core residues within 8 Å of it. A cluster is reported when it has at least min_pocket_residues members and a mean pLDDT of at least 50. No cavity, solvent-accessible surface or ligand is computed.

Each of up to 10 clusters reports its residue numbers, mean pLDDT, radius of gyration, centroid offset from the model centroid, and geometry_score: an uncalibrated 0 to 100 sum of four equally weighted sub-scores (residue count, radius of gyration, mean pLDDT, centroid offset) that only orders the clusters. estimated_volume_angstrom3 is the volume of a sphere with the cluster's radius of gyration, not a cavity volume.

Validation status: in an internal audit of 19 AlphaFold models the top-ranked cluster was enriched for the PDBe-KB ligand-binding site in 4 of the 18 proteins that had one, and every reported cluster scored 55 or more (LIMITATIONS.md L11). For existing clients the same clusters are also returned under the earlier names, as deprecated aliases: putative_pockets and n_pockets_found, with entries keyed pocket_id, druggability_index and druggability_components; their druggability_label is NOT_ASSESSED. To locate binding sites, use a dedicated pocket detector such as fpocket or P2Rank.

Input fields

params.uniprot_id: UniProt accession of the AlphaFold model to cluster, e.g. 'P24941' (CDK2). params.min_pocket_residues: Minimum cluster size, 3 to 20 (default 4).

detect_intrinsically_disordered async

detect_intrinsically_disordered(params: UniProtInput) -> dict[str, Any]

Flag low-confidence modeled regions as intrinsic-disorder candidates.

Reads per-residue AlphaFold pLDDT from PDB C-alpha records and groups contiguous runs below 50. Low pLDDT may reflect intrinsic disorder, missing binding partners, alternate conformations, or model uncertainty; it is NOT independent evidence that a region is disordered.

Returns model-local residue indices, observed PDB chain/residue identifiers, and positional descriptions of low-pLDDT runs. These labels describe model geometry, not validated linkers, tails, disorder or function. Legacy idr_fraction and disordered_residue_count remain deprecated numeric aliases of low-pLDDT measurements, NOT validated intrinsic-disorder assays. Prefer low_plddt_* fields for scientific interpretation. PDB numbering is not mapped to full-length UniProt via SIFTS here.

This implementation is a reproducible screening heuristic, not a validated disorder predictor, biomolecular mechanism classifier, or clinical result. For background on intrinsic disorder, see Ruff & Pappu (2021), J Mol Biol. 433:167208; that paper does not validate these cutoffs or code.

Input fields

params.uniprot_id: UniProt accession.

get_protein_structure async

get_protein_structure(params: StructureRetrievalInput) -> dict[str, Any]

Retrieve a protein's AlphaFold model: metadata, download URLs, optional coordinates.

The single entry point for getting the predicted structure itself. Returns the AlphaFold DB entry metadata — entry ID, model version and creation date, organism, gene, UniProt description, the amino-acid sequence and its length, and the model's mean pLDDT — plus stable download URLs for the PDB and mmCIF coordinate files, the PAE matrix, and the AlphaMissense substitutions CSV. The PAE image URL is only present in legacy API responses. Set include_coordinates to embed the full PDB coordinate text directly.

Use the sibling structure tools for interpretation rather than retrieval, so their scopes don't overlap: analyze_structural_confidence for a pLDDT/PAE confidence read, score_binding_pocket_geometry for geometric clusters of core residues (not validated pockets), compute_topology_fingerprint for an exploratory Cα summary vector, and detect_intrinsically_disordered for low-pLDDT intervals. This tool hands you the structure and its handles; it does not score or interpret the model.

Returns structure_available: false when no model was retrieved, and retrieval_status says why. no_prediction_returned: AlphaFold DB answered without a model for the accession, an expected coverage gap. request_failed: the request was blocked (offline mode) or failed, which is not evidence that no prediction exists.

With include_coordinates, coordinates_pdb is the file that this same record advertises (file_urls.pdb); no second prediction lookup is made. coordinates_status is retrieved, no_coordinates_returned (the record advertises no PDB file, or the file is empty) or request_failed (the request for that file failed, HTTP 404 included). coordinates_pdb is empty unless the status is retrieved; when it is empty, coordinates_error gives the reason.

Input fields

params.uniprot_id: UniProt accession to retrieve, e.g. 'P38398' (BRCA1). params.include_coordinates: Embed the full PDB coordinate text (large); default false returns metadata and download URLs only.