Skip to main content
Glama

Cluster Core Residues by Geometry (Unvalidated Pocket Heuristic)

score_binding_pocket_geometry
Read-onlyIdempotent

Cluster and score core AlphaFold model residues by geometry to prioritize candidate binding-pocket regions for dedicated validation.

Instructions

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "params": "<params>"
    },
    "name": "score_binding_pocket_geometry"
  }
}

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.6.0
    • changedInput schema / properties / params / properties / min_pocket_residues / description
      Previous value: -"Minimum number of residues to define a pocket."New value: +"Minimum cluster size: a core residue seeds a cluster only when at least this many unassigned core Cα atoms, itself included, lie within 8 Å of it. Higher values suppress small clusters. The name is historical; clusters are not validated pockets."
    • changedInput schema / properties / params / properties / uniprot_id / description
      Previous value: -"UniProt accession for binding-pocket geometry analysis."New value: +"UniProt accession of the protein whose AlphaFold DB model is clustered, e.g. 'P24941' (CDK2). Six or ten characters; an isoform suffix such as 'P04637-2' selects that isoform's model when AlphaFold DB provides one."
  2. Changed1 schema field changedv1.5.2
    • changedInput schema / properties / params / properties / uniprot_id / pattern
      Previous value: -"^[A-Z][0-9][A-Z0-9]{3}[0-9](?:[A-Z][0-9][A-Z0-9]{3}[0-9])?$"New value: +"^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})(?:-[1-9][0-9]*)?$"
  3. First observedv1.1.8

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations give readOnly/idempotent/openWorld, and the description goes well beyond them: it discloses the filter thresholds (min cluster size, mean pLDDT ≥ 50), the 10-cluster cap, and warns that geometry_score is uncalibrated and only ordering-useful. It even pre-empts a likely misinterpretation by stating estimated_volume_angstrom3 is a sphere from radius of gyration, not a cavity volume — no contradiction with the readOnly/idempotent annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but well-ordered: disclaimer first, then algorithm, then output fields, then validation evidence, then deprecated aliases. Nearly every sentence carries distinct information; the deprecated-alias paragraph is verbose but justified because it prevents an agent from misreading druggability_index as a real druggability score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nested-parameter, output-schema-bearing tool with non-obvious return fields, the description covers everything an agent needs: preconditions (AlphaFold DB model), algorithm, filtering, output semantics, and limitations. The output schema exists, yet the description still flags which returned field names are misleading, which is exactly the gap the schema cannot close.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description supplies meaning the schema alone would not convey as clearly: min_pocket_residues is tied to the seeding rule ("a core residue seeds a cluster only when…") and to the report threshold, and it discloses hardcoded constraints that are not parameters at all (8 Å radius, pLDDT ≥ 50). The historical-name caveat for min_pocket_residues adds genuine semantic value, though the schema's own parameter descriptions carry much of the same ground.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Cluster the core residues of an AlphaFold model by geometry" gives a specific verb (cluster) and resource (core residues), and the description immediately disclaims the binding-pocket framing implied by the tool name. It also names the concrete algorithmic scope (Cα atoms within the 60th percentile of centroid distances, 8 Å greedy seeds), so an agent knows exactly what operations this performs versus siblings like assess_target_druggability.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when NOT to use it ("Not a validated binding-pocket detector; no druggability class is assigned") and routes the agent to the correct alternatives by name: "use a dedicated pocket detector such as fpocket or P2Rank." It also supplies the honest hit-rate context (top cluster enriched in 4 of 18 proteins with a known site) so an agent can weigh the result.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.