Skip to main content
Glama

Retrieve AlphaFold Protein Structure

get_protein_structure
Read-onlyIdempotent

Retrieve a protein's AlphaFold model metadata, download URLs, and optional PDB coordinates by UniProt accession for structural analysis.

Instructions

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.

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": "get_protein_structure"
  }
}

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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]*)?$"
  2. Addedv1.4.3

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnly/openWorld/idempotent; the description goes well beyond by enumerating failure modes and their meaning — structure_available: false with retrieval_status values (no_prediction_returned as "an expected coverage gap" vs request_failed which is "not evidence that no prediction exists"). It also discloses coordinate status semantics (retrieved / no_coordinates_returned / request_failed incl. HTTP 404) and the important caveat that no second prediction lookup is made.

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?

Front-loaded with the one-line summary, then grouped logically into: what is returned, sibling routing, failure statuses, coordinate behavior. Dense but almost every sentence carries distinct operational information. Minor waste in the legacy-PAE-image-URL aside, which is marginal for an API consumer.

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 complex retrieval tool with a nested schema and an existing output schema, the description covers the remaining gaps: what the payload contains, how partial-success and failure are signaled, and how coordinate embedding behaves. An agent can call this correctly and interpret both success and degraded outcomes without further reading.

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?

With schema description coverage reported at 0%, the description must carry parameter meaning, and it does for include_coordinates: it explains that true embeds the full PDB text (large, hundreds of KB) while false returns metadata plus download URLs from which files can be fetched. The uniprot_id accession semantics and format are only conveyed by example in the schema, not elaborated in the description, so this is strong but not complete.

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?

Opens with a specific verb+resource+scope: "Retrieve a protein's AlphaFold model: metadata, download URLs, optional coordinates." It then enumerates exactly what is returned (entry ID, model version, organism, sequence, mean pLDDT, PDB/mmCIF/PAE/AlphaMissense URLs) and explicitly frames itself as "the single entry point for getting the predicted structure itself," which separates it from interpretation siblings.

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?

Provides an explicit when-to-use vs when-not-to-use split: use this for retrieval, use siblings for interpretation, and names each sibling with the exact scope it owns (confidence read, geometric clusters, topology vector, disorder intervals). It even cautions that pockets from score_binding_pocket_geometry are "not validated pockets," giving the agent a real routing decision.

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