plant-genomics-mcp

Overview Schema Source Related Servers Discussions Admin

PDBe: Experimental Structures

experimental_structures

Read-onlyIdempotent

Retrieve experimentally solved protein structures (X-ray, cryo-EM, NMR) for a plant locus from PDBe, ranked by quality. Includes PDB id, method, resolution, coverage; reports found=false when absent.

Instructions

Fetch experimentally-solved (X-ray / cryo-EM / NMR) protein structures for a locus from PDBe (www.ebi.ac.uk/pdbe; free, no key). Resolves the locus → UniProt accession, then returns PDBe's best_structures mapping ranked best-first: per entry the PDB id, chain, experimental method, resolution, coverage, and modelled residue span. Most plant proteins have NO deposited structure — that returns found=false (a normal outcome, not an error); a locus with no UniProt entry raises a typed NotFoundError. structure_count is the true total even when the list is capped. Complements alphafold_structure (the predicted view). Works for all 12 organisms (UniProt-keyed). Defaults to arabidopsis_thaliana; pass organism= for other species.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`locus`	Yes	e.g. AT4G09760 (Arabidopsis), Os01g0100100 (rice RAP-DB)
`organism`	No	Plant organism — accepts canonical slug (arabidopsis_thaliana), scientific or common name, or NCBI taxid	arabidopsis_thaliana

Output Schema

TableJSON Schema

Name	Required	Description
`found`	Yes	True if any experimental structure is deposited
`locus`	Yes
`total`	Yes	How many PDBe best_structures rows (one per chain) exist upstream for this query, all pages (pre-cap) (#123)
`returned`	Yes	Rows in this payload (#123)
`accession`	Yes	Resolved UniProt accession
`truncated`	Yes	True if the structure list was capped
`structures`	No	Best-first {pdb_id, chain_id, experimental_method, resolution, coverage, …}
`entry_count`	Yes	Distinct PDB entries among the rows; structure_count counts chains (#123)
`structure_count`	Yes	PDBe rows, pre-cap — one per CHAIN, not per entry (see entry_count)
`upstream_version`	No	PDBe release that produced THIS response, — always null today: this backend states no release on its responses; upstream_release(backend='pdbe') reports the release its own endpoint calls current at query time, or why there is none. null means PDBe did not state one — never that no release exists, and never inferred from a separate metadata call, which can describe a different release than the one that answered.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.27.0Sep 27, 2026

changedOutput schema / properties / upstream_version / description

Previous value: -"PDBe release that produced THIS response, — always null today: this backend states no release on its responses. null means PDBe did not state one — never that no release exists, and never inferred from a separate metadata call, which can describe a different release than the one that answered."New value: +"PDBe release that produced THIS response, — always null today: this backend states no release on its responses; upstream_release(backend='pdbe') reports the release its own endpoint calls current at query time, or why there is none. null means PDBe did not state one — never that no release exists, and never inferred from a separate metadata call, which can describe a different release than the one that answered."

Changed7 schema fields changedv1.22.0Sep 24, 2026

changedOutput schema / description

Previous value: -"PDBe experimentally-solved structures for a locus (via UniProt).\n\nThe locus is resolved to a UniProt accession, then PDBe's ``best_structures``\nmapping is queried (ranked best-first). ``found=False`` (empty list) means no\ndeposited structure — the common plant case (a 404), not an error.\nComplements ``AlphaFoldStructure`` (the predicted view). ``structure_count``\nis the true total even when the list is capped."New value: +"PDBe experimentally-solved structures for a locus (via UniProt).\n\nThe locus is resolved to a UniProt accession, then PDBe's ``best_structures``\nmapping is queried (ranked best-first). ``found=False`` (empty list) means no\ndeposited structure — the common plant case (a 404), not an error.\nComplements ``AlphaFoldStructure`` (the predicted view). ``structure_count``\n(= ``total``) counts per-chain rows before the cap; ``entry_count`` counts\ndistinct PDB entries."

addedOutput schema / properties / entry_count

Added value: +{
+  "description": "Distinct PDB entries among the rows; structure_count counts chains (#123)",
+  "title": "Entry Count",
+  "type": "integer"
+}

addedOutput schema / properties / returned

Added value: +{
+  "description": "Rows in this payload (#123)",
+  "title": "Returned",
+  "type": "integer"
+}

changedOutput schema / properties / structure_count / description

Previous value: -"Total deposited structures (pre-cap)"New value: +"PDBe rows, pre-cap — one per CHAIN, not per entry (see entry_count)"

addedOutput schema / properties / total

Added value: +{
+  "description": "How many PDBe best_structures rows (one per chain) exist upstream for this query, all pages (pre-cap) (#123)",
+  "title": "Total",
+  "type": "integer"
+}

addedOutput schema / properties / upstream_version

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "PDBe release that produced THIS response, — always null today: this backend states no release on its responses. null means PDBe did not state one — never that no release exists, and never inferred from a separate metadata call, which can describe a different release than the one that answered.",
+  "title": "Upstream Version"
+}

changedOutput schema / required

Previous value: -[
-  "locus",
-  "accession",
-  "found",
-  "structure_count",
-  "truncated"
-]New value: +[
+  "total",
+  "returned",
+  "entry_count",
+  "locus",
+  "accession",
+  "found",
+  "structure_count",
+  "truncated"
+]

Addedv1.18.2Jul 24, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive hints, and the description adds substantial behavioral detail: locus-to-UniProt resolution, best_structures ranking and fields, found=false as a non-error, a typed NotFoundError, and the fact that structure_count is the true total even when the list is capped. This gives an agent accurate expectations for edge cases and error semantics well beyond the annotation hints.

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?

The description is dense but well-structured: it front-loads the core purpose, then progressively covers result contents, edge cases, the relationship to alphafold_structure, organism scope, and defaults. Every clause carries useful information with no filler, though the length is at the upper edge of what is ideal for a single tool description.

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?

With an output schema in place, return-value details are covered elsewhere, and the description fills the remaining gaps: supported organisms, the no-structure normal case, the no-UniProt error case, the capped-list behavior, and the relationship to a sibling tool. For a two-parameter, read-only fetch with rich annotations and a full output schema, nothing critical is missing.

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?

Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description adds meaning by explaining that results are UniProt-keyed and that locus resolution precedes the PDBe query, which clarifies how organism interacts with the lookup. It also reinforces the default organism and that organism= can be passed for other species, going slightly beyond the schema's default declaration.

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?

The description opens with a specific verb ('Fetch') and a clear resource ('experimentally-solved protein structures for a locus from PDBe'), enumerating the experimental methods (X-ray / cryo-EM / NMR). It explicitly distinguishes itself from alphafold_structure by labeling that tool as the predicted view, so there is no ambiguity about what this tool retrieves.

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

Usage Guidelines4/5

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

It names alphafold_structure as the predicted counterpart, implying the experimental-versus-predicted decision an agent needs to make. It also explains the expected found=false outcome for most plant proteins and calls out the NotFoundError case, which prevents an agent from misclassifying normal results as failures. The guidance is strong but the 'when-not-to-use' instruction is more implied than explicitly stated.

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

Deploy Server