RCSB PDB

Discover the fields available on a Data API object, from the live GraphQL schema. Use this to find exactly what to request in a rcsb_get_* tool's `fields=` argument. The rcsb_get_* default selections are compact summaries, but the underlying GraphQL types have far more (e.g. CoreEntry has ~100 fields). Every path it returns is verified against the live schema, so it is safe to pass to `fields=` 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=` accepts EITHER dotted paths ("rcsb_polymer_entity.pdbx_description") OR GraphQL nested-brace syntax ("rcsb_polymer_entity { pdbx_description }"); the two may be mixed, and multiple paths are separated by spaces or commas. Three ways to use it, all returning dotted paths ready for `fields=`: - FIND which tool has a field: pass ONLY `query` and omit `object_key`. Searches every object and answers with the tool to call and the path to give it, best matches first. Start here whenever you know what you want but not where it lives — rcsb_describe_data_object(query="release_date") -> rcsb_get_entries + "rcsb_accession_info.initial_release_date". A SEARCH ATTRIBUTE PATH works as the `query` too: every attribute from rcsb_list_pdb_search_attributes is also a Data API field, so pasting one in tells you which tool fetches the value you can filter on. - SEARCH one object: name `object_key` as well, to keep only that object's matches. - BROWSE a level: name `object_key` and omit `query` to list its own fields, then drill into a nested one with `into`. Workflow: rcsb_describe_data_object("entries") -> spot a nested object such as "rcsb_entry_info" -> rcsb_describe_data_object("entries", into="rcsb_entry_info") to list its leaves…

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. Args: object_key: A Sequence Coordinates root field. (alignments and group_alignments share the SequenceAlignments type; the annotation roots share SequenceAnnotations.) into: Optional dot-path of nested object field(s) to scope to, e.g. "target_alignments" or "features.feature_positions". query: Optional case-insensitive keyword, matched against each field's path (relative to the scope) and its description. max_depth: How many levels to walk (1-6). Omit it: the default follows what you are doing — 1 when browsing, 3 when searching. The schema bottoms out at 3. Returns: {object_key,…

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. Args: query: Free-text disease / condition, e.g. "cystic fibrosis", "breast cancer". limit: Max MONDO terms to return. with_pdb_counts: If true (default), annotate each with pdb_entry_count (PDB entries carrying it, via annotation_lineage.id). 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. Args: query: Free-text enzyme / reaction, e.g. "alcohol dehydrogenase", "protein kinase". limit: Max EC numbers to return. with_pdb_counts: If true (default), annotate each with pdb_entry_count (PDB entries carrying it, via rcsb_ec_lineage.id). 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. Args: query: Free-text function / process / location, e.g. "kinase activity", "DNA repair". namespace: Optional GO aspect to restrict to. Omit to search all three. limit: Max GO terms to return. with_pdb_counts: If true (default), annotate each term with pdb_entry_count (PDB entries carrying it, via annotation_lineage.id). 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. Args: query: Free-text domain/family name, e.g. "SH2 domain", "immunoglobulin". entry_type: Optional type filter. Omit to return all types. limit: Max entries to return. with_pdb_counts: If true (default), annotate each entry with pdb_entry_count (PDB entries carrying it). 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. Args: query: Free-text organism / clade / common name, e.g. "human", "mammals", "E. coli". limit: Max taxa to return. with_pdb_counts: If true (default), annotate each taxon with pdb_entry_count (PDB entries from it or any organism beneath it, via taxonomy_lineage.id) — this also disambiguates a species from its strains. 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.* Args: assembly_ids: entry-assembly, e.g. ["4HHB-1"] — exactly what rcsb_search_request returns with return_type="assembly". Unknown IDs are returned under "not_found". Do not guess "-1". Assembly 1 essentially always exists, so the guess succeeds silently, but an entry's assemblies differ in composition and the first is not necessarily the one carrying what you searched for. Take it from an assembly search hit, or from rcsb_entry_container_identifiers.assembly_ids on rcsb_get_entries. fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_assembly_info.polymer_entity_instance_count"); discover/verify paths with rcsb_describe_data_object("assemblies").

Fetch branched (carbohydrate / oligosaccharide) entities, e.g. ["5FMB_2"]. Default fields: description, weight, copy count, branch type, and component count. Args: entity_ids: entry + entity number, e.g. ["5FMB_2"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_branched_entity.pdbx_description"); discover/verify paths with rcsb_describe_data_object("branched_entities").

Fetch branched entity instances (individual glycan chains), e.g. ["5FMB.C"]. Default fields: the entry/entity/chain identifiers. Args: instance_ids: entry.asym_id (glycan chain), e.g. ["5FMB.C"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_branched_entity_instance_container_identifiers.asym_id"); discover/verify paths with rcsb_describe_data_object("branched_entity_instances").

Fetch chemical components / ligands by their short codes, e.g. ["HEM", "ATP"]. Default fields: name, formula, weight, type, SMILES, InChIKey. Args: comp_ids: chemical-component short codes, e.g. ["HEM", "ATP"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "chem_comp.name"); discover/verify paths with rcsb_describe_data_object("chem_comps").

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). Args: entry_ids: 4-character PDB entry codes, e.g. ["4HHB", "1MBN"]; pass a one-element list for a single entry. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "struct.title"); discover/verify paths with rcsb_describe_data_object("entries").

Fetch entry groups (clusters of related entries) by group ID. Default fields: group name, description, member count, and member ids. Args: group_ids: entry-group ids, e.g. ["G_1002266"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_group_info.group_name"); discover/verify paths with rcsb_describe_data_object("entry_groups").

Fetch provenance/method metadata for a grouping, e.g. "provenance_sequence_identity". Default fields: the aggregation method/type and provenance id. Args: group_provenance_id: a provenance token, e.g. "provenance_sequence_identity". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_group_aggregation_method.type"); discover/verify paths with rcsb_describe_data_object("group_provenance").

Fetch assembly interfaces, e.g. ["1BMV-1.1"] (entry-assembly.interface). Default fields: buried area, character, composition, residue count. Args: interface_ids: entry-assembly.interface, e.g. ["1BMV-1.1"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_interface_info.interface_area"); discover/verify paths with rcsb_describe_data_object("interfaces").

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. Args: entity_ids: entry + non-polymer entity number, e.g. ["4HHB_3"] — exactly what rcsb_search_request returns with return_type="non_polymer_entity". Unknown IDs are returned under "not_found". Do not guess the number: entity numbering is shared with the polymers and they take the low values, so a ligand is rarely "_1" and that guess lands in not_found. Take it from rcsb_entry_container_identifiers .non_polymer_entity_ids on rcsb_get_entries, or from a search hit. fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_nonpolymer_entity.pdbx_description"); discover/verify paths with rcsb_describe_data_object("nonpolymer_entities").

Fetch non-polymer entity groups (clusters of related ligands) by group ID. Default fields: group name, description, member count, and member ids. Args: group_ids: non-polymer entity group ids, e.g. ["ATP"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_group_info.group_name"); discover/verify paths with rcsb_describe_data_object("nonpolymer_entity_groups").

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. Args: instance_ids: entry.asym_id, e.g. ["4HHB.E"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_nonpolymer_entity_instance_container_identifiers.comp_id"); discover/verify paths with rcsb_describe_data_object("nonpolymer_entity_instances").

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.* Args: entity_ids: entry + entity number, e.g. ["4HHB_1"] — exactly what rcsb_search_request returns with return_type="polymer_entity". Unknown IDs are returned under "not_found". NEVER form one by appending _1 to an entry id. Entity numbers are assigned per deposition and carry no meaning: "<ENTRY>_1" essentially always exists, so the guess returns valid data for whatever molecule happens to be numbered first — a DIFFERENT protein, or DNA/RNA — and nothing in the response marks it wrong. Take the number from a search hit, or from rcsb_entry_container_identifiers.polymer_entity_ids on rcsb_get_entries. fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_polymer_entity.pdbx_description"); discover/verify paths with rcsb_describe_data_object("polymer_entities").

Fetch polymer entity groups (e.g. sequence clusters), e.g. ["85_70"]. Default fields: group name, description, member count, and member ids. Args: group_ids: sequence-cluster group ids, e.g. ["85_70"]. Unknown IDs are returned under "not_found". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_group_info.group_name"); discover/verify paths with rcsb_describe_data_object("polymer_entity_groups").

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. Args: instance_ids: entry.asym_id (chain), e.g. ["4HHB.A"] — exactly what rcsb_search_request returns with return_type="polymer_instance". Unknown IDs are returned under "not_found". Do not guess ".A". It is the LABEL asym_id, not the author chain — the instance an author calls chain A is often lettered differently — and any entry with more than one chain has several instances, so a guessed ".A" silently returns a chain that is not the one that matched. Take it from a polymer_instance search hit, or from rcsb_get_entries with fields= "polymer_entities{rcsb_polymer_entity_container_identifiers{asym_ids}}" — the entry's own container identifiers stop at entity and assembly ids, so chains need that traversal. fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_polymer_instance_info.modeled_residue_count"); discover/verify paths with rcsb_describe_data_object("polymer_entity_instances").

Fetch the PubMed record for a citation by its integer ID, e.g. 6726807. Default fields: PubMed Central ID, DOI, abstract text. Args: pubmed_id: integer PubMed ID, e.g. 6726807. fields: Optional GraphQL selection replacing the curated default (e.g. rcsb_pubmed_doi); discover/verify paths with rcsb_describe_data_object("pubmed").

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`. Args: uniprot_id: a UniProt accession, e.g. "P69905". fields: Optional GraphQL selection replacing the curated default (e.g. "rcsb_uniprot_protein.name"); discover/verify paths with rcsb_describe_data_object("uniprot").

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, then use it in `rcsb_query_attribute` (or as an `attributes` entry on any `rcsb_search_*`). Args: query: Optional case-insensitive keyword to filter the catalog. Matched as a LITERAL SUBSTRING against the attribute path and description, so pass ONE keyword ("resolution", "comp_id"), not a phrase — a multi-word query only matches where those exact words are adjacent in a description. Omit to return everything. schema: Which catalog — "structure" (~675 attrs: entry/entity/assembly/instance) or "chemical" (~57 attrs: chemical-component). Paths from the chemical catalog need chemical_attributes=True on rcsb_query_attribute. 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 ~15% 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 matches nothing. `nested_group` appears on the ~22% 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 o…

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}, ] Args: attributes: One or more conditions, each {attribute, operator, value, negation?, case_sensitive?}. Operators are TYPE-SPECIFIC (strings use exact_match/in or contains_words/contains_phrase; numbers and dates use greater/greater_or_equal/ less/less_or_equal/equals/range; any type supports exists). A numeric value may be a number or a numeric string; a range value is a {from, to, include_lower, include_upper} object whose bounds are EXCLUSIVE unless the include flags say otherwise. Omit `value` for `exists`. Some attributes accept only a FIXED SET of values — exptl.method is "X-RAY DIFFRACTION" / "ELECTRON MICROSCOPY" / ..., not "cryo-EM".…

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. Args: value: The descriptor (SMILES like "CC(=O)Oc1ccccc1C(=O)O", or an InChI string) or the formula (e.g. "C9H8O4"). Case is preserved — element symbols and SMILES are case-sensitive. query_type: "descriptor" (default) or "formula". descriptor_type: "SMILES" (default) or "InChI"; descriptor queries only. match_type: How strictly to match the graph (descriptor queries only). Whole- molecule: graph-exact / graph-strict / graph-relaxed (default) / graph-relaxed-stereo, or fingerprint-similarity for "chemically similar". Substructure — find larger molecules CONTAINING this fragment — use a sub-struct-graph-* variant (e.g. "sub-struct-graph-relaxed"). match_subset: Formula queries only. True matches components that merely contain the given atoms (and possibly others); False (default) requires the formula to match exactly. 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. Args: queries: Two or more query documents from any rcsb_query_* tool (including this one). Pass each through exactly as returned. logical_operator: "and" (default) or "or". 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. Args: query: Terms matched case-insensitively against all text annotations. Quote a phrase to require adjacency (e.g. '"DNA polymerase"'); separate words narrow the results; a trailing '*' is a prefix wildcard. AND/OR/NOT are NOT boolean operators here — combine conditions with rcsb_query_composer instead. 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. Args: pattern: The motif, written in the grammar named by pattern_type. pattern_type: "prosite" (default) for PROSITE syntax like "C-x(2,4)-C-x(3)-[LIVMFYWC]"; "regex" for a regular expression like "C..H[LIVF]"; "simple" for simple wildcards where X matches any residue (e.g. "NXS"). sequence_type: "protein" (default), "dna", or "rna". 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. Args: sequence: One-letter sequence; whitespace is ignored. FASTA headers must be removed. sequence_type: "protein" (default), "dna", or "rna". identity_cutoff: Minimum fractional identity 0-1 (default 0.3). Raise toward 0.9 for close homologs, lower for remote ones. evalue_cutoff: Maximum E-value (default 1.0); lower is stricter. 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. Args: entry_id: Reference PDB entry defining the motif, e.g. "2MNR". residue_ids: 2-10 residues defining the motif, each {"label_asym_id": <chain>, "label_seq_id": <int>, "struct_oper_id"?: <str>}. IMPORTANT: these are the mmCIF *label* identifiers (the internal numbering), which often DIFFER from the author residue numbers seen in papers and on the PDB site. If you only have author numbering, resolve it first (e.g. via rcsb_get_polymer_entity_instances) — author numbers give wrong/no hits. Example (enolase catalytic residues): [{"label_asym_id":"A","label_seq_id":162}, {"label_asym_id":"A","label_seq_id":193}, {"label_asym_id":"A","label_seq_id":219}] backbone_distance_tolerance: Backbone distance tolerance in A, integer 0-3 (default 1). side_chain_distance_tolerance: Side-chain distance tolerance in A, integer 0-3 (default 1). angle_tolerance: Angle tolerance in multiples of 20 degrees, integer 0-3 (default 1). rmsd_cutoff: Maximum RMSD of accepted hits (default 2.0). atom_pairing_scheme: ALL, BACKBONE, SIDE_CHAIN (default), or PSEUDO_ATOMS. motif_pruning_strategy: NONE or KRUSKAL (default). exchanges: Optional per-position residue alternatives, each {"residue_id": {...}, "allowed": [<3-letter codes>]}, to match variants of the motif. 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. Args: entry_id: Reference PDB entry, e.g. "4HHB". assembly_id: Reference a whole assembly, e.g. "1". Defaults to assembly "1" when neither this nor asym_id is given; mutually exclusive with asym_id. asym_id: Reference a single chain instead, e.g. "A" (the mmCIF label id). 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. Args: query: The query document returned by an rcsb_query_* tool, passed through unchanged. return_type: What kind of identifier to return: Type Description Example Data API tool entry whole structure "4HHB" -> rcsb_get_entries polymer_entity one molecule "4HHB_1" -> rcsb_get_polymer_entities non_polymer_entity ligand entity "4HHB_3" -> rcsb_get_nonpolymer_entities polymer_instance one chain "4HHB.A" -> rcsb_get_polymer_entity_instances assembly biological assembly "4HHB-1" -> rcsb_get_assemblies mol_definition chemical component "HEM" -> rcsb_get_chem_comps If conditions granularity is finer than entry (e.g. entity, instance, ...), an entry matches when EACH condition holds on SOME subunit — not necessarily the same one. Omit it to use the default implied by the query: Query Return type rcsb_query_fulltext -> entry rcsb_query_attribute -> entry rcsb_query_sequence -> polymer_entity rcsb_query_seqmotif -> polymer_entity rcsb_query_structure -> assembly (assembly_id in query) / polymer_instance (asym_id in query) rcsb_query_strucmotif -> assembly rcsb_query_chem…

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" Args: query_id: The sequence id, in the from_ref system's format — UNIPROT "P69905", NCBI_PROTEIN "NP_000508", NCBI_GENOME "NC_000016", PDB_ENTITY "4HHB_1" (entry_entityNumber), PDB_INSTANCE "4HHB.A" (entry.asym_id). PDB ids must be ENTITY-level, never a bare entry: for a whole entry, first get its polymer entity ids (4HHB -> 4HHB_1, 4HHB_2) and query each one. from_ref: Reference system of query_id. to_ref: Reference system to map onto. seq_range: Optional [begin, end] (1-based) to restrict the query region. fields: Optional GraphQL selection to override the default.

Fetch positional sequence annotations (features) for one sequence. Args: query_id: The sequence id, e.g. "4HHB_1" (PDB_ENTITY) or "P69905" (UNIPROT). reference: Reference system query_id is given in. sources: Annotation provenance — which source(s) to pull features from. seq_range: Optional [begin, end] (1-based) to restrict the region. filters: Optional list of {field, operation, source?, values} filter dicts, where field is TARGET_ID or TYPE and operation is CONTAINS or EQUALS. fields: Optional GraphQL selection to override the default.

Fetch alignments among the members of a sequence group. Args: group: How the group is defined. group_id: The group id, e.g. "P69905" (a UniProt accession) for MATCHING_UNIPROT_ACCESSION. filter_terms: Optional list of target ids to restrict the group members. fields: Optional GraphQL selection to override the default.

Fetch annotations across the members of a sequence group. Args: group: How the group is defined. group_id: The group id, e.g. "P69905" for MATCHING_UNIPROT_ACCESSION. sources: Annotation provenance — which source(s) to pull features from. summary: If true, return a positional summary aggregated across the group (group_annotations_summary) instead of per-member annotations. filters: Optional filter dicts (see rcsb_seqcoord_annotations). fields: Optional GraphQL selection to override the default.