RCSB PDB

Discover the fields available on a Data API object, from the live GraphQL schema. Use this to find what to request in a rcsb_get_* tool's `fields=` argument: its default selection is a compact summary of a far richer type (CoreEntry has ~100 fields). Every path returned is verified against the live schema, so it is safe to pass directly. NEVER invent, guess, or infer a field path from memory, from a naming convention, or from another API. An unverified path fails GraphQL schema validation and wastes the call. Paths shown in a rcsb_get_* tool's own description or examples are already verified — use those directly; for anything else, confirm it here FIRST. `fields=` takes dotted paths ("rcsb_polymer_entity.pdbx_description"), GraphQL brace syntax ("rcsb_polymer_entity { pdbx_description }"), or both, separated by spaces or commas. Start with only a `query` when you know what you want but not where it lives: it searches every object and answers with the tool to call and the path to give it, best matches first — rcsb_describe_data_object(query="release_date") -> rcsb_get_entries + "rcsb_accession_info.initial_release_date". Name an `object_key` to search just that object, or omit `query` to browse its fields level by level with `into`. Returns: For a named object: {object_key, graphql_type, path, query, max_depth, field_count, fields, truncated?, note?}. Searching every object: the same with object_key null plus `searched`, and each field also names the rcsb_get_* `tool` that owns it. Each field is {path, kind, type, list, description, searchable?}: `kind` is "scalar" (select it directly) or "object" (drill in, or select with a sub-selection); `searchable` (about 3% of fields) marks one you can ALSO filter on with rcsb_query_attribute. A field is reported once, under the object reaching it most directly. A capped result sets `truncated`, and `note` says how to narrow it.

Discover the fields available on a Sequence Coordinates object, from the live schema. The Sequence Coordinates analogue of rcsb_describe_data_object, with the same shape: the rcsb_seqcoord_* tools return a compact default selection; use this to find what else you can request via their `fields=` argument. Every path it returns is verified against the live schema, so it is safe to pass to `fields=` directly. Browse a level, drill in / scope with `into`, or pass `query` to flatten the tree into dotted paths and keep only matching fields. The walk depth follows which one you are doing, so you do not have to set it: browsing lists one level, searching goes three deep. This schema is small and bottoms out at 3 levels (~20-31 fields per object), so a search covers an object in full in ONE call: rcsb_describe_seqcoord_object("alignments", max_depth=3) -> pick paths -> call rcsb_seqcoord_alignments(..., fields="target_alignments{ ... }"). Each returned field has path (dotted, ready for `fields=`), kind ("scalar" leaf or "object"), type, list (whether it's a list), and description (when present). NEVER invent, guess, or infer a field path — an unverified path fails schema validation and wastes the call. `fields=` accepts dotted paths or GraphQL nested-brace syntax, the two may be mixed, and multiple paths are separated by spaces or commas. Returns: {object_key, graphql_type, path, query, max_depth, field_count, fields:[{path, kind, type, list, description}], truncated?, note?}.

Resolve a free-text disease, disorder, syndrome, or condition (e.g. diabetes, cancer, Alzheimer disease, cystic fibrosis) to MONDO ontology ids, for precise disease-based PDB searches instead of keyword guessing. Use for ANY request mentioning a disease/disorder/syndrome/condition — "structures involved in / associated with / linked to <disease>", "proteins implicated in <disease>". Resolve the phrase to a MONDO id here, then filter on it with rcsb_query_attribute: exact_match on rcsb_uniprot_annotation.annotation_lineage.id, id AS A STRING ("MONDO:0005148"). The *_lineage.id paths are HIERARCHICAL — they match the term AND everything beneath it; use `in` with several ids to broaden. A MONDO id therefore finds the disease and its subtypes. Results are based on how each entry's text matched your query. Broader, synonym, or differently-worded terms for the same concept may produce different results. Rank is unrelated to how much of the archive each term covers. Returns: {query, count, diseases:[{id, name, matched_synonym?, pdb_entry_count?}]}. `matched_synonym` appears only when the formal MONDO name does not contain your words — it names the synonym that did match.

Resolve a free-text enzyme, enzyme class, or catalyzed reaction (e.g. alcohol dehydrogenase, protease, kinase, DNA polymerase, hydrolase, oxidoreductase) to Enzyme Commission (EC) numbers, for precise EC-based PDB searches instead of keyword guessing. Use this when a request references an enzyme, enzyme class, or reaction — including "enzymes that catalyze / break down / degrade / synthesize / hydrolyze / phosphorylate ...". Resolve the phrase to an EC number here, then filter on it with rcsb_query_attribute: exact_match on rcsb_polymer_entity.rcsb_ec_lineage.id, EC number AS A STRING. The *_lineage.id paths are HIERARCHICAL — they match the term AND everything beneath it; use `in` with several ids to broaden. A partial EC like "3.4.21" therefore matches the whole sub-subclass. Results are based on how each entry's text matched your query. Broader, synonym, or differently-worded terms for the same concept may produce different results. Rank is unrelated to how much of the archive each term covers. Returns: {query, count, enzymes:[{ec, name, pdb_entry_count?}]}.

Resolve a free-text molecular function, biological process, or cellular component / location (e.g. kinase activity, ATP binding, DNA repair, apoptosis, signal transduction, mitochondrial membrane, nucleus) to Gene Ontology (GO) terms, so you can run precise GO-based PDB searches instead of keyword guessing. Use this when a request involves what a protein DOES or where it acts — "proteins that <do X> / are involved in / participate in / are responsible for ...", "localized to / located in ...". Resolve the phrase to a GO id here, then filter on it with rcsb_query_attribute: exact_match on rcsb_polymer_entity_annotation.annotation_lineage.id, id AS A STRING ("GO:0004672"). The *_lineage.id paths are HIERARCHICAL — they match the term AND everything beneath it; use `in` with several ids to broaden. For ONLY that exact term without descendants use annotation_id instead. Results are based on how each entry's text matched your query. Broader, synonym, or differently-worded terms for the same concept may produce different results. Rank is unrelated to how much of the archive each term covers. Returns: {query, namespace, count, terms:[{id, name, aspect, pdb_entry_count?}]}.

Resolve a free-text protein domain, family, or fold (e.g. SH2 domain, immunoglobulin fold, zinc finger, beta-barrel, WD40 repeat, kinase domain) to InterPro entries, for precise InterPro-based PDB searches instead of keyword guessing. Use this whenever a request references a protein DOMAIN, FAMILY, or fold — "structures containing / with a <domain>", "<domain>-containing proteins", "members of the <family> family". Resolve the phrase to an accession here, then filter on it with rcsb_query_attribute: exact_match on rcsb_polymer_entity_annotation.annotation_id, accession AS A STRING ("IPR000719"). Lineage paths are not available; broaden with `in` over several accessions instead (IPR and PF mix freely). Ids come from InterPro ("IPR000719") or Pfam ("PF07859") — `source_database` on each entry says which. Both filter on the same attribute; nothing else needs to change. Results are based on how each entry's text matched your query. Broader, synonym, or differently-worded terms for the same concept may produce different results. Rank is unrelated to how much of the archive each term covers. Returns: {query, entry_type, count, entries:[{id, name, type, source_database, matched_text?, pdb_entry_count?}]}. `matched_text` appears only when the entry's NAME does not contain your words — it quotes the text that did match.

Resolve a free-text organism, common name, or clade (e.g. human, mouse, baker's yeast, Escherichia coli, mammals, bacteria, primates) to NCBI Taxonomy ids, for precise taxonomy-based PDB searches instead of keyword guessing. Use when a request restricts structures by SOURCE ORGANISM or any higher taxon — a common name you want as a canonical taxon ("human", "fruit fly"), or a CLADE, which a plain name search cannot expand. Resolve the phrase to a taxon id here, then filter on it with rcsb_query_attribute: exact_match on rcsb_entity_source_organism.taxonomy_lineage.id, id AS A STRING ("9606", not 9606 — a bare number does not match). The *_lineage.id paths are HIERARCHICAL — they match the term AND everything beneath it; use `in` with several ids to broaden. A clade id ("40674" = Mammalia) therefore finds every organism beneath it; for a known exact species ncbi_scientific_name exact_match also works. An informal, polyphyletic group ("filamentous fungi", "extremophiles", "algae") is NOT a taxon and has no id: resolve the nearest CONTAINING taxon, then classify each hit from the lineage its own record returns. Results are based on how each entry's text matched your query. Broader, synonym, or differently-worded terms for the same concept may produce different results. Rank is unrelated to how much of the archive each term covers. Returns: {query, count, taxa:[{tax_id, scientific_name, common_name, rank, pdb_entry_count?}]}.

Fetch biological assemblies, e.g. ["4HHB-1"] (entry-assembly). Default fields: composition counts and oligomeric state. Assembly-based (complex) annotations can be fetched adding rcsb_assembly_annotation.* fields, and positional features rcsb_assembly_feature.*

Fetch branched (carbohydrate / oligosaccharide) entities, e.g. ["5FMB_2"]. Default fields: description, weight, copy count, branch type, and component count.

Fetch branched entity instances (individual glycan chains), e.g. ["5FMB.C"]. Default fields: the entry/entity/chain identifiers.

Fetch chemical components / ligands by their short codes, e.g. ["HEM", "ATP"]. Default fields: name, formula, weight, type, SMILES, InChIKey.

Fetch metadata for one or more PDB entries (title, method, resolution, size, dates, and primary citation). The response also lists the entry's component ids under rcsb_entry_container_identifiers — use these to drill into the structure. They are bare numbers; compose them with the entry id to call the matching rcsb_get_* tool: polymer_entity_ids/non_polymer_entity_ids "N" -> "<ENTRY>_N" (rcsb_get_polymer_entities / rcsb_get_nonpolymer_entities); assembly_ids "N" -> "<ENTRY>-N" (rcsb_get_assemblies).

Fetch entry groups (clusters of related entries) by group ID. Default fields: group name, description, member count, and member ids.

Fetch provenance/method metadata for a grouping, e.g. "provenance_sequence_identity". Default fields: the aggregation method/type and provenance id.

Fetch assembly interfaces, e.g. ["1BMV-1.1"] (entry-assembly.interface). Default fields: buried area, character, composition, residue count.

Fetch non-polymer (ligand/cofactor) entities, e.g. ["4HHB_3"]. Default fields: description, weight, copy count, and the bound chemical component ID. Use rcsb_get_chem_comps for the chemistry of that component.

Fetch non-polymer entity groups (clusters of related ligands) by group ID. Default fields: group name, description, member count, and member ids.

Fetch non-polymer entity instances (individual bound ligands), e.g. ["4HHB.E"]. Default fields: the entry/entity/chain identifiers, bound component id, and author seq id.

Fetch polymer entities (protein/nucleic-acid molecules) — description, length, weight, and source organism. Default fields: description, length, weight, and source organism. Polymer-based (sequence) annotations can be fetched adding rcsb_polymer_entity_annotation.* fields, and positional features adding rcsb_polymer_entity_feature.*

Fetch polymer entity groups (e.g. sequence clusters), e.g. ["85_70"]. Default fields: group name, description, member count, and member ids.

Fetch polymer entity instances (individual chains), e.g. ["4HHB.A"] (entry.asym_id). Instance-based (chain) annotations can be fetched adding rcsb_polymer_instance_annotation.* fields, and positional features rcsb_polymer_instance_feature.* Default fields: the entry/entity/chain identifiers and modeled-residue count.

Fetch the PubMed record for a citation by its integer ID, e.g. 6726807. Default fields: PubMed Central ID, DOI, abstract text.

Fetch the UniProt record RCSB maps to an accession, e.g. "P69905". Default fields give a functional snapshot: accession(s), entry name, protein and gene names, EC number, the UniProt function comment, source organism, and keywords (which often summarize biology directly, e.g. "ATP-binding", "Viral attachment to host entry receptor"). RCSB's UniProt integration is rich — `fields` can also pull the heavier annotation sets (kept out of the default because they can run to hundreds of entries): `rcsb_uniprot_annotation` (GO terms, InterPro, disease associations), `rcsb_uniprot_feature` (domains, sites, binding sites, sequence variants), and `rcsb_uniprot_external_reference`.

Discover the RCSB PDB Search schema: attribute paths, value types, and operators. Call this FIRST when a request resolves to a clear attribute and value but you don't know the exact path; pick the attribute here, build the condition with `rcsb_query_attribute`, then execute with `rcsb_search_request`. Returns: {count, match_mode, attributes, note?}. `attributes` holds {attribute, type, operators, description, enum?, nested_group?} records — the RCSB/PDB attribute path (e.g. "rcsb_entry_info.resolution_combined"), its value type (string/number/integer/date), the operators it supports (exact_match, greater, range, exists, ...), and a human-readable description. `enum` appears on the ~16% of attributes that accept only a FIXED SET of values (e.g. exptl.method); when it does, use one of those values verbatim — anything else is rejected by rcsb_query_attribute. `nested_group` appears on the ~19% stored in NESTED DOCUMENTS — an entry has many citations, an entity many binding affinities — and its value is the container path. For these, grouping selects the semantics: conditions sharing a nested_group built in ONE rcsb_query_attribute call with nothing else in it must hold on the SAME record; in separate calls each is matched independently. Group the ones that describe one record, leave the rest apart. The value is NOT the attribute's first path segment for all of them, so read it rather than deriving it. `match_mode` is "exact" (every word matched, best match first), "partial" (only some did — read `note`), "none" (nothing matched — read `note`), or "all" (query omitted, whole catalog).

Build a STRUCTURED query from attribute conditions — the precise alternative to keyword search, and preferred whenever a request resolves to clear attribute(s) and value(s). NEVER invent, guess, or infer an attribute path: call rcsb_list_pdb_search_attributes first if you don't know it or its operators. For a biological concept, resolve it to an ontology id with the matching rcsb_find_* tool and filter on that annotation. If a resolver returns no usable id, or a concept filter yields no hits, fall back to rcsb_query_fulltext for the concept. For ordinary constraints — resolution, organism, dates — an empty result is a valid answer: report it, don't keyword-search instead. An attribute path also works as the `query` for rcsb_describe_data_object: every attribute here is also a Data API field, so pasting one in tells you which rcsb_get_* tool fetches the value. Example ("human X-ray structures better than 2 A"): attributes=[ {"attribute": "rcsb_entity_source_organism.ncbi_scientific_name", "operator": "exact_match", "value": "Homo sapiens"}, {"attribute": "exptl.method", "operator": "exact_match", "value": "X-RAY DIFFRACTION"}, {"attribute": "rcsb_entry_info.resolution_combined", "operator": "less", "value": 2.0}, ] Returns: A query document — pass it to rcsb_search_request, or to rcsb_query_composer. Note the per-hit `score` of a pure attribute filter is near-uniform and carries NO biological meaning; don't rank hits by it.

Build a CHEMICAL query from a SMILES/InChI descriptor or a molecular formula. Use for ligand and small-molecule questions where you have the chemistry itself. To find a ligand by NAME, use rcsb_query_fulltext or filter on a chemical attribute. Returns: A query document — pass it to rcsb_search_request, or to rcsb_query_composer.

Combine query documents with one AND/OR — call repeatedly to nest. You do NOT need this for conditions that share a single operator: several attribute conditions ANDed together are one rcsb_query_attribute call, and a list of alternatives for one attribute is better expressed with the `in` operator than with OR. Reach for the composer when a query needs BOTH operators, or mixes services: * (human OR mouse) AND resolution < 2 A -> build the OR group with rcsb_query_attribute(logical_operator="or"), build the resolution condition, then compose the two with "and". * sequence-similar to X AND containing ligand Y -> compose rcsb_query_sequence with rcsb_query_attribute. Nest by feeding a composed document straight back in as one of `queries`. Groups that share this call's operator are folded in rather than nested, so repeated composition stays flat and readable. Returns: A query document — pass it to rcsb_search_request, or back into this tool. A query mixing two services has no single meaningful relevance ranking, so hits come back in the API's default order; set `sort_by` on rcsb_search_request if the order matters.

Build a FREE-TEXT keyword query (e.g. "CRISPR Cas9", "hemoglobin"). Best for broad or exploratory lookups. When a request resolves to a clear attribute and value, prefer rcsb_query_attribute — more precise, and it avoids spurious keyword matches. BEFORE keyword-searching a biological CONCEPT (disease/function/domain/ enzyme/organism), resolve it to an ontology id with the matching rcsb_find_* tool and filter on the annotation instead; fall back to keywords only if that yields nothing. Matching spans many text attributes beyond the title — abstracts, keywords, synonyms, author names — so judge each hit yourself: a high `score` is text-relevance, NOT biological importance; never tell the user one hit is better than another because its score is higher. For evidence on a hit, rcsb_get_entries returns its title and, for many entries, a PubMed abstract (pubmed.rcsb_pubmed_abstract_text). Broader, synonym, or differently-worded terms for the same concept may produce different results. Returns: A query document — pass it to rcsb_search_request to run it, or to rcsb_query_composer to combine it with other queries first.

Build a SHORT SEQUENCE-MOTIF query — a pattern, not a full sequence. Use for active-site signatures, N-glycosylation sequons, zinc fingers, and similar short patterns. For a whole sequence use rcsb_query_sequence; for a 3D arrangement of residues use rcsb_query_strucmotif. Returns: A query document — pass it to rcsb_search_request, or to rcsb_query_composer.

Build a SEQUENCE-SIMILARITY query (MMseqs2, BLAST-like) from a raw sequence. Use when you have actual residues to match. For a short motif or pattern use rcsb_query_seqmotif; for a named protein use rcsb_query_fulltext or a resolver. Returns: A query document — pass it to rcsb_search_request, or to rcsb_query_composer.

Build a 3D STRUCTURAL-MOTIF query — a geometric arrangement of specific residues. Geometry-based, and different from rcsb_query_structure (whole-shape similarity) and rcsb_query_seqmotif (sequence pattern). Use it for catalytic triads, binding sites, metal-coordination geometries, and similar. Returns: A query document — pass it to rcsb_search_request, or to rcsb_query_composer.

Build a 3D SHAPE-SIMILARITY query against an existing PDB structure. Whole-shape similarity — use it for "structures shaped like X" / "same fold as X". For a geometric arrangement of specific residues use rcsb_query_strucmotif; for sequence similarity use rcsb_query_sequence. Returns: A query document — pass it to rcsb_search_request, or to rcsb_query_composer.

Render a structure-search report as a styled, self-contained HTML page. Call this LAST, after the searches and rcsb_get_* calls that produce the values shown in the report. Supply facts only: the page is rendered from a fixed server-side template, so do not write HTML yourself and do not rewrite what this tool returns. Key fields of ``report``: title: page heading describing the search. api_calls: one per Search/Data/Sequence-Coordinates call, using the ``editor`` object the tool returned VERBATIM. Resolver and discovery tools have no editor link — pass label and tool_name only. result_type: what your ids ARE — "entry" for PDB entry ids (4HHB, the default) or "ligand" for chemical component ids (ATP). It must match the ids you send: a mismatch resolves nothing, and every derived value comes back empty. results: the identifiers you are reporting, in the order you want them ranked, each ``{"id": ..., "evidence": {...}}``. Evidence has two fields: ``grounds`` (the tool-returned value the match rests on) and optional ``interpretation`` (your own reading of it). Splitting them is what stops your inference from being read as something the archive returned. data_usage: ordered narrative of how each call shaped the final set; each item's ``body`` is plain prose — your own account of how you worked. Returns: RenderReportResult with EITHER a `url` or `html` (never both), plus template_version. Prefer `url` — it is a self-contained link that renders the report on demand; deliver it to the user as-is. `html` is only returned as a fallback; write it to a `.html` file.

RUN a query built by the rcsb_query_* tools and return matching PDB identifiers. Every search ends here: build with rcsb_query_fulltext / rcsb_query_attribute / rcsb_query_sequence / rcsb_query_chemical / rcsb_query_structure / rcsb_query_seqmotif / rcsb_query_strucmotif, optionally join with rcsb_query_composer, then execute with this tool. Nothing is searched until you call it — a query document on its own is not a result. Results are IDENTIFIERS only. Batch them into rcsb_get_entries, or the rcsb_get_* tool matching `return_type`, to get metadata. Returns: {total_count, returned, result_type, fetch_with, offset, has_more, next_offset, hits:[{id, score}], editor} — `result_type` is the kind of identifier that came back and `fetch_with` names the rcsb_get_* tool that takes it, so check those before batching the ids onward. `editor` opens the query in the RCSB search UI. With `all_hits` the paging fields are omitted; with `facets` returns {total_count, facets, editor} instead of hits. A `notes` list appears only when the results need a caveat; read it before describing the hits or treating them as complete.

Cross-reference a sequence across PDB, UniProt, and NCBI, with aligned ranges. This is the tool for "which X identifiers correspond to this sequence?" across databases — including NCBI. The RCSB Data API only cross-references UniProt, so use THIS tool for NCBI RefSeq protein / genome mappings (and PDB<->UniProt too). The returned target_alignments[].target_id values are the mapped identifiers in the to_ref system, each with its aligned regions. Examples: - "What NCBI proteins map to PDB entity 4HHB_1?" query_id="4HHB_1", from_ref="PDB_ENTITY", to_ref="NCBI_PROTEIN" - "Which PDB entities correspond to UniProt P69905?" query_id="P69905", from_ref="UNIPROT", to_ref="PDB_ENTITY"

Residue-level features of one PDB polymer entity (4HHB_1) or instance (4HHB.A), positioned on its sequence. The tool for questions about specific residues: which form an active site, bind a ligand or metal, are modified, glycosylated or disulfide-bonded, lie in a domain, helix or membrane segment, are unobserved or poorly fitted. Without feature_types every feature is returned. An answer too large to return (an entity's chain features come once per copy) fails with the feature types the sequence has and their counts: ask again for the ones needed, or for one instance. With feature_types only those come back, from the sources that have them.