io.github.rcsb/rcsb-mcp

Official

by rcsb

Overview Schema Related Servers Score Discussions

Python

Remote

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.14.0
Disambiguation5/5
Every tool targets a distinct resource or action: searches differ by modality (text, attribute, sequence, chemical, structure, sequence motif, structural motif), resolvers by ontology type, and get tools by entity kind. Descriptions explicitly call out differences, e.g., rcsb_search_by_structure vs rcsb_search_strucmotif, so an agent can reliably pick the right tool.
Naming Consistency4/5
Tool names overwhelmingly follow rcsb_<verb>_<object> with consistent verb families: search_by_*, get_*, describe_*, find_*, seqcoord_*. The main deviation is rcsb_search_strucmotif lacking the 'by' present in rcsb_search_by_seqmotif, which slightly breaks the otherwise predictable pattern.
Tool Count2/5
36 tools is well beyond the 15-tool typical range and even beyond the 16-25 'heavy' band. While the RCSB PDB archive is a large domain, this many tools makes the MCP surface feel bloated and harder for an agent to navigate efficiently.
Completeness5/5
The surface is thorough for a read-only structure archive: multiple search modalities (text, attribute, sequence, chemical, structure, motifs), ontology resolvers, schema discovery tools, sequence-coordinate cross-referencing, and retrieval for every entity type (entries, polymers, non-polymers, branched, assemblies, interfaces, groups, UniProt, PubMed). Paging, batching, and reporting are handled, leaving no obvious dead ends.
Average 4.6/5 across 36 of 36 tools scored. Lowest: 3.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 149 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Fetch' aligns with these. However, the description adds no additional behavioral context such as pagination, rate limits, result scope limits, or side effects. It does not contradict the annotations, but it also does not enrich them.
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 concise: one opening sentence plus a structured Args list. Every line provides necessary information without unnecessary prose. The structure is clean and easy to scan, though the Args section is formatted as a simple list rather than using rich formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, together with the output schema, covers the invocation and likely return values. However, it does not elaborate on the two enum values for 'group' (MATCHING_UNIPROT_ACCESSION and SEQUENCE_IDENTITY) or how the 'group_id' format differs between them. This leaves a meaningful gap for an agent choosing the right group_id format. Overall, it is minimally viable but not comprehensive.
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 schema has 0% description coverage, and the description's Args section compensates by explaining each parameter: 'group' defines the grouping method, 'group_id' includes an example ('P69905') for MATCHING_UNIPROT_ACCESSION, 'filter_terms' restricts members, and 'fields' overrides the GraphQL selection. This significantly adds meaning beyond the bare schema, though the 'fields' explanation is terse.
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 clearly states the tool's function: 'Fetch alignments among the members of a sequence group.' It identifies a specific verb and resource, and the phrase 'sequence group' differentiates it from the sibling tool rcsb_seqcoord_alignments, which handles alignments without the group component.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by explaining that it fetches alignments for groups, but it does not explicitly state when to use this tool versus alternatives like rcsb_seqcoord_alignments or rcsb_seqcoord_group_annotations. No exclusions or alternative guidance is provided, leaving the choice to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that setting `summary=true` returns a positional summary instead of per-member annotations, plus references to `rcsb_seqcoord_annotations` for filters. However, it does not elaborate on response format, pagination, or potential limitations, so the added transparency is modest.
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 opens with a single, clear sentence and then uses a structured Args list. Each parameter line is brief yet informative, with no unnecessary words. The structure is conventional and easy to parse, though it could be slightly more compact by merging some lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, enums, output schema, rich annotations), the description covers the essential inputs and the key behavioral switch (`summary`). It references external sources for advanced options (`filters`, `fields`). It does not address how this tool relates to sibling tools, but the output schema and annotations fill many gaps, making the description sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates thoroughly by explaining every parameter: `group` ('How the group is defined'), `group_id` with a concrete example ('P69905' for MATCHING_UNIPROT_ACCESSION), `sources` ('Annotation provenance'), `summary` with behavior and the underlying type, `filters` with a cross-reference, and `fields` as an optional GraphQL override. This provides meaning well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Fetch annotations') and resource ('members of a sequence group'), clearly conveying the tool's core function. However, it does not explicitly differentiate from the closely related sibling tool `rcsb_seqcoord_annotations`, which likely handles individual sequence annotations, so the distinction relies on the tool name and implied 'group' context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given for when to use this tool versus alternatives. The description focuses entirely on parameter explanations and omits any mention of use cases, exclusions, or comparisons to sibling tools like `rcsb_seqcoord_annotations`, leaving the agent to infer appropriate usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safe read-only nature (readOnlyHint, idempotentHint, non-destructive). The description adds useful behavioral details: unknown IDs are returned under 'not_found', the default field set is enumerated, and users are directed to rcsb_describe_data_object for custom field discovery. This goes beyond the annotations without contradicting them.
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 well-structured with a brief opening followed by separate Args entries. It is slightly lengthy due to the GraphQL example, but every sentence contributes necessary information with no filler. The format is scannable and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides default fields, error handling for unknown IDs, and a path discovery mechanism. Since an output schema is present (per context), detailed return structure is not required. It is complete enough for safe selection and invocation, though it does not mention pagination or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are thoroughly explained. entity_ids is described with a concrete example and behavior for unknown IDs; fields is explained with GraphQL selection syntax and a pointer to discover valid paths. This fully compensates for the schema's 0% description coverage and adds significant semantic meaning.
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 'Fetch branched (carbohydrate / oligosaccharide) entities' which clearly specifies the verb, resource, and scope. The example and the sibling context distinguish it from polymer/nonpolymer or instance-level getters, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus siblings like rcsb_get_branched_entity_instances or rcsb_get_polymer_entities. It focuses on mechanics (fields, defaults) but does not state selection criteria or exclude alternatives, leaving usage context to be inferred from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavior about default fields and that fields can be overridden, but it does not disclose side effects, auth requirements, or other behavioral nuances. It is consistent with 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?
The description is compact and well-structured: a one-sentence purpose, a default-fields note, and two parameter entries. It is slightly technical but every sentence earns its place; no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. It covers parameters, provides examples, and references a companion tool. However, it relies on external 'server instructions' and lacks a note on when to prefer this tool over sibling group-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully explains both parameters: group_provenance_id is 'a provenance token' with an example, and fields is described as an optional GraphQL selection with an example and a pointer to rcsb_describe_data_object. This provides essential semantic value beyond the bare schema.
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 clearly states 'Fetch provenance/method metadata for a grouping' with a concrete example. The verb and resource are specific, and it is distinct from sibling group tools that likely retrieve group data rather than provenance metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool via its purpose and gives an example. It references rcsb_describe_data_object for field discovery, which is an alternative, but it does not explicitly compare with sibling group tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that it fetches features and that filters can restrict results, but it does not disclose additional behavioral traits like pagination, rate limits, or handling of invalid IDs. It does not contradict annotations and provides some useful context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-structured docstring: a one-sentence summary followed by a concise Args list. No wasted words; each parameter explanation is minimal yet complete, and the first line front-loads the tool's purpose.
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?
Given the output schema exists, the description needn't explain return values. It covers all essential invocation details: required parameters, optional parameters, constraints, and examples. The tool's scope ('for one sequence') is stated, and the combination of parameter semantics and annotations makes it sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains every parameter with clear meaning: query_id with concrete examples, reference as the coordinate system, sources as provenance, seq_range with 1-based bounds, filters with field/operation/value structure, and fields as a GraphQL override. This is comprehensive and actionable.
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 states a specific action ('Fetch') and a specific resource ('positional sequence annotations for one sequence'), clearly distinguishing it from siblings like alignments or group annotations. The scope is explicit ('for one sequence'), which differentiates it from group-oriented tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (fetching features for a single sequence, with optional region filters and provenance selection) but does not explicitly state when to prefer this tool over alternatives such as rcsb_seqcoord_group_annotations or alignments. There is no mention of excluded cases or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavior: default fields returned, unknown IDs handled via 'not_found', and fields override capability. This goes beyond annotation information without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with a clear purpose sentence, default fields note, and an Args section. Every sentence serves a purpose, and the format is easy to scan without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only data-fetching tool with an output schema and strong annotations, the description covers the essential aspects: what it retrieves, defaults, parameter semantics, and unknown-ID handling. It omits potential details like pagination or rate limits, but these are less critical given the straightforward getter nature and existing schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates by explaining both parameters: group_ids as sequence-cluster group IDs with example and unknown-ID behavior, and fields as an optional GraphQL selection with a discovery path. This provides substantial meaning beyond the bare schema.
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 clearly states the tool fetches polymer entity groups, provides a concrete example (sequence clusters with "85_70"), and distinguishes itself from sibling group-fetching tools like rcsb_get_nonpolymer_entity_groups and rcsb_get_entry_groups. The verb 'fetch' and specific resource 'polymer entity groups' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the resource and providing example IDs, but does not explicitly state when to use this tool over alternatives (e.g., rcsb_get_entry_groups) or give exclusions. It does point to rcsb_describe_data_object for field discovery, which is helpful but not a full usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context: the default fields returned, that unknown group IDs are returned under 'not_found', and that the fields argument is a GraphQL selector that replaces the default. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with a purpose line, a default-fields line, and a clean Args section. Every sentence adds information—no fluff, no repetition of schema properties—and the format is easy to scan.
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?
Given the tool has only two parameters and an output schema, the description covers the core purpose, default output, parameter semantics, and how to extend the query. It leaves nothing essential unexplained; the output schema handles return value details, so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does. It explains group_ids with an example and the 'not_found' behavior, and fields with an example and a pointer to rcsb_describe_data_object for discovering valid paths. Both parameters are clearly documented beyond their schema definitions.
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 states a specific verb ('Fetch') and resource ('non-polymer entity groups') with a clarifying parenthetical ('clusters of related ligands'). It distinguishes from sibling tools like rcsb_get_polymer_entity_groups and rcsb_get_nonpolymer_entities by explicitly naming the entity-group scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs nonpolymer entity group data by ID, but it does not explicitly state when to use this tool over alternatives or mention exclusion criteria. There is no 'when to use' or 'when not to use' guidance beyond the resource name, so it remains at the implied-usage level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds valuable behavioral context beyond annotations: default fields returned, unknown IDs placed under 'not_found', and the ability to override defaults with a custom GraphQL field selection. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief summary, default fields line, and a concise Args list. It avoids redundancy and each sentence provides useful information without unnecessary padding.
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?
Given the tool's simplicity, the description covers all essential aspects: purpose, ID format, default fields, error handling for unknown IDs, and how to customize fields. With an output schema present, the description need not explain return values, so it is fully complete for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must justify parameter meanings. It thoroughly explains instance_ids with format (entry.asym_id) and example, plus error handling for unknown IDs. It also explains the fields parameter as an optional GraphQL selection, replacing the curated default, and points to rcsb_describe_data_object for discovery.
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 clearly states it fetches polymer entity instances (individual chains), with an explicit example of the instance ID format. This distinguishes it from sibling tools like rcsb_get_polymer_entities (which returns entities, not chain-level instances) and other instance-specific tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'Fetch polymer entity instances (individual chains)' and provides parameter details, but it does not explicitly mention when to use this tool over alternatives or when not to use it. No sibling tool is referenced, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, open-world, idempotence, and non-destructive behavior. The description adds valuable behavioral detail: unknown IDs are returned under 'not_found', and the default fields are specified. It also explains the 'fields' parameter's effect on the response, which goes beyond what schema annotations alone provide.
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 well-structured with a clear opening sentence, a default-fields note, and a compact list of arguments. It is slightly long due to the detailed field-path example, but every sentence contributes useful information. The front-loaded purpose makes it easy to scan.
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 only two parameters (one required), a read-only annotation set, and an existing output schema, the description covers all essential context: what the tool does, default behavior, parameter semantics, error handling for unknown IDs, and where to find valid field paths. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It explains assembly_ids with an example and the 'not_found' behavior, and fields with a concrete GraphQL path example plus a pointer to rcsb_describe_data_object for discovering valid paths. This is far more helpful than the bare schema properties.
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 'Fetch biological assemblies' – a specific verb and resource – and provides the concrete example '4HHB-1' (entry-assembly), which disambiguates it from sibling get-tools like rcsb_get_entries or rcsb_get_polymer_entities. The intent is immediately clear and distinct.
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?
The description clearly implies when to use this tool: whenever you need biological assembly data. It also provides guidance on how to customize queries with the 'fields' parameter and directs users to rcsb_describe_data_object for path discovery. It does not explicitly state when NOT to use it (e.g., for entries or polymer entities), but the resource-specific naming and examples make the context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral details: unknown IDs are returned under 'not_found', the fields parameter replaces the curated default selection, and field paths can be discovered programmatically. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose, then uses efficient structured lines for defaults and arguments. Every sentence adds necessary information, with no fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a moderate retrieval use case and an output schema present, the description covers the key points: what the tool fetches, default fields, parameter semantics, and edge-case behavior. It does not detail the exact output structure, but the output schema handles that, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero descriptions, so the description carries full burden. It thoroughly explains group_ids with an example and the 'not_found' behavior, and explains fields as an optional GraphQL selection with an example and a discovery method. Both parameters are fully contextualized.
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-resource pairing: 'Fetch entry groups (clusters of related entries) by group ID.' This both defines the resource type and clearly distinguishes it from sibling tools like rcsb_get_entries or rcsb_get_polymer_entity_groups.
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?
The description provides clear context for how to use the tool, including default fields, the use of group_ids with an example, and the behavior for unknown IDs. It also instructs how to discover valid field paths via rcsb_describe_data_object, but it does not explicitly state when to choose this tool over alternative group-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent, so the description adds value by specifying the default fields (PubMed Central ID, DOI, abstract text) and the fact that `fields` is a GraphQL selection. It also provides a discovery path for valid field names. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 70 words and well organized: a purpose sentence, a note on default fields, and a clear args list. Every sentence contributes necessary information, and the structure front-loads the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID tool, this description is quite complete: it covers purpose, parameters, default fields, and how to discover custom field paths. It does not discuss error handling or output shape, but an output schema exists, so that is acceptable. A small gap is the lack of explicit guidance on when not to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates: it explains `pubmed_id` as an integer PubMed ID with an example, and `fields` as an optional GraphQL selection with an example and a pointer to rcsb_describe_data_object for verifying paths. This adds substantial meaning beyond the bare schema.
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 clearly states 'Fetch the PubMed record for a citation by its integer ID' – a specific verb and resource. It distinguishes itself from other get_* tools by naming the PubMed record and providing an example ID. There is no ambiguity about what the tool does.
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 explains the required input (pubmed_id) and optional fields, and points users to rcsb_describe_data_object for field discovery. It does not explicitly contrast with search tools, but the instruction to use an integer ID implies this tool is for known identifiers rather than searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: the output format (query, count, enzymes with ec/name/pdb_entry_count), the effect of with_pdb_counts, and a pointer to resolver guidance for lineage semantics. It also clarifies the mapping to EC-based searches. This goes beyond what annotations provide, though it doesn't discuss edge cases like empty results or ambiguous queries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loading the purpose in the first sentence, followed by usage guidance, parameter semantics, and return format. Every sentence is informative, with no fluff. The use of bullets and concise examples makes it easy to parse.
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?
The description is complete for an AI agent to select and invoke the tool correctly. It explains the tool's role in a larger workflow (EC-based PDB searches), gives concrete query examples, details all parameters, and describes the return structure. It also references server instructions for deeper resolver guidance, filling any residual gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates with an 'Args' section explaining each parameter: 'query: Free-text enzyme / reaction', 'limit: Max EC numbers to return', and 'with_pdb_counts: If true (default), annotate each with pdb_entry_count'. It also includes examples and return format details, adding meaning beyond the raw schema.
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 clearly states the tool resolves free-text enzyme/reaction phrases to EC numbers for precise PDB searches. It uses a specific verb ('Resolve') and resource ('enzyme class' to EC numbers), and distinguishes from siblings like rcsb_find_go_terms by focusing on enzymes and explicitly mentioning 'instead of keyword guessing'.
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?
The description explicitly says 'Use this when a request references an enzyme, enzyme class, or reaction' with concrete examples, and provides workflow guidance ('Resolve the phrase to an EC number here, then search by it'). It does not name alternative tools for when-not-to-use, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent. The description adds valuable behavior: it's a precursor to precise PDB searches, clarifies GO aspect options, and explains the optional PDB count enrichment. It also notes lineage semantics but defers detailed guidance to server instructions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose. It uses compact sections for usage, args, and returns. Every sentence earns its place, with examples that clarify rather than pad.
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 4-param tool with no schema descriptions and only a prose return format, the description is complete. It covers when to use, what each param means, and the exact return structure. The pointer to server instructions for lineage semantics is an acceptable delegation for deeper details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility. It explains all four parameters with intent, defaults, and examples (e.g., namespace restriction, limit as max terms, with_pdb_counts behavior). This goes well beyond the schema titles.
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 clearly states the tool resolves free-text biological function/process/location phrases to GO terms. It uses a specific verb (resolve) and resource (GO terms), distinguishes from search tools in the sibling list, and provides concrete examples.
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?
The description explicitly says 'Use this when a request involves what a protein DOES or where it acts' and gives example phrasing patterns. It contrasts with keyword guessing but does not name or exclude specific sibling tools, so it falls short of full when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive behavior. The description adds valuable behavioral context by noting that unknown IDs are returned under 'not_found' and that default fields are entry/entity/chain identifiers. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the purpose with an example, followed by default fields and clear parameter breakdowns. Every sentence contributes useful information with no redundancy.
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?
Given the tool's simplicity, the annotations, and the presence of an output schema, the description adequately covers both parameters, default behavior, error handling, and points to a way to discover field paths. It is complete for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), so the description must carry the full burden. It thoroughly explains instance_ids with format and example, and fields as an optional GraphQL selection with a concrete example and cross-reference to rcsb_describe_data_object. This fully compensates for the schema gap.
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 uses the specific verb 'Fetch' with the resource 'branched entity instances', clarifying that these are 'individual glycan chains' and providing a concrete example. This clearly distinguishes it from sibling tools like rcsb_get_branched_entities, which fetches entities rather than instances.
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?
The description implies when to use the tool (for retrieving specific glycan chain instances) through the term 'instances' and the example format. However, it does not explicitly mention alternatives or when not to use it, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, etc.), the description discloses useful behavior: unknown IDs are returned under 'not_found' and default fields are curated. This adds context about response behavior and field customization, though it doesn't cover all possible behaviors (e.g., rate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence states the core function, followed by default fields and parameter details. Every sentence adds value, with no filler or repetition.
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?
The description is complete for this tool's complexity. It provides the input format, parameter semantics, default behavior, and points to an auxiliary tool for field discovery. The presence of an output schema covers return value details, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains both parameters: comp_ids as short codes with example and not_found behavior, and fields as an optional GraphQL selection with a specific example and a pointer to discover valid paths. This fully compensates for the missing schema descriptions.
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?
Description clearly states the tool fetches chemical components/ligands by short codes, with examples. The verb 'Fetch' and resource 'chemical components / ligands' make the purpose unambiguous and distinguish it from sibling tools like rcsb_get_entries or rcsb_get_polymer_entities.
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?
The description provides clear context: use this to fetch chemical components by short codes. It also mentions rcsb_describe_data_object as an alternative for field discovery, offering guidance on when to use that tool. No explicit exclusions are given, but the scope is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent behavior, so the description doesn't need to restate that. It adds useful quirks: unknown IDs are returned under 'not_found', and `fields` replaces the default selection. This provides behavioral insight beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line purpose, a default-fields note, and an Args list. Every sentence adds value — no padding or redundancy.
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 2-parameter tool with an output schema, the description covers purpose, argument semantics, defaults, unknown-ID handling, and field customization. It is self-contained and gives the agent everything needed to invoke correctly without requiring the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. `interface_ids` is explained with format and error behavior; `fields` gets a clear explanation, an example GraphQL path, and a discovery method. This is far beyond what the bare schema offers.
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 starts with 'Fetch assembly interfaces' — a specific verb and resource — and gives the exact format (e.g., ["1BMV-1.1"]). This clearly distinguishes it from sibling `get_*` and search tools.
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?
The description gives clear context for when to use this tool (fetching interfaces by IDs) and explains the `fields` parameter with a pointer to `rcsb_describe_data_object` for discovering paths. It does not explicitly contrast with sibling tools, but the usage context is informative and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (read-only, idempotent, open-world), the description discloses the default field set, the behavior of unknown IDs ('returned under not_found'), and the fact that fields replaces the curated default. This adds meaningful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and then structured into default fields, cross-tool guidance, and an Args section. Every sentence adds value; there is no repetition of schema or annotation info.
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?
Given the read-only nature, output schema presence, and sibling context, this description is complete: it covers what the tool returns by default, how to customize fields, what happens with bad IDs, and where to go for related chemistry data. No critical gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates: it explains entity_ids as 'entry + entity number' with an example, and fields as 'Optional GraphQL selection replacing the curated default' with an example and discovery path. Both parameters get actionable semantics.
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?
Description opens with 'Fetch non-polymer (ligand/cofactor) entities' – a specific verb and resource. It distinguishes itself from related sibling tools by explicitly naming the counterpart rcsb_get_chem_comps for component chemistry, and the term 'non-polymer' is a clear contrast to polymer/branched sibling entities.
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?
The description tells the agent to use rcsb_get_chem_comps when the chemistry of the bound component is needed, and points to rcsb_describe_data_object for field path discovery. It does not explicitly state when to avoid this tool, but the alternative pointers give clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds valuable behavioral detail: unknown IDs are returned under 'not_found', and fields replaces a curated default. This goes beyond the safety flags, though it does not disclose auth or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: a one-line purpose, a default-fields line, and a compact Args list. There is no redundant text; every sentence adds informational value.
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 present and strong annotations, the description still covers default fields, field customization, unknown-ID behavior, and related tool integration. It is comprehensive for a read-only retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains entity_ids with format, example, and provenance from rcsb_search_by_sequence, and fields with an example and a discovery path via rcsb_describe_data_object. Both parameters receive meaningful semantics beyond the bare schema.
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 clearly states 'Fetch polymer entities (protein/nucleic-acid molecules)' with a specific verb and resource. This distinguishes it from sibling tools like rcsb_get_nonpolymer_entities and rcsb_get_branched_entities.
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?
The description implies a clear usage context by noting that entity_ids are 'exactly what rcsb_search_by_sequence returns', linking it to a sequence search workflow. It does not explicitly name alternative tools or exclusions, but the polymer-specific scope and the reference to related tools provide sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: pagination via next_offset, all_hits limits (refused above 10000), sorting restrictions (full-text-only attributes rejected, mol_definition rejected), and the facts that facets returns a distribution instead of hits. This goes far beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Despite its length, the description is tightly organized: purpose sentence, Args list with one line per parameter, and a Returns block. Every sentence adds necessary info for a 16-parameter tool. It avoids fluff and uses parentheticals to pack meaning efficiently.
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?
Given the high complexity (16 parameters, nested attribute filters, multiple return types), the description covers all parameters, explains the two possible return shapes (hits vs facets), and references server instructions for faceting/grouping details. The output schema is described in Returns, so no major gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully. For example, match_type explains the strict-to-relaxed spectrum and substructure variants, match_subset is defined for formula queries, sort_by details which attributes are sortable and what is rejected, and attributes describes how to combine with AND/OR. Every parameter receives meaningful, non-redundant explanation.
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 'Search PDB chemical components by structure (SMILES/InChI) or formula,' clearly stating the specific verb, resource, and scope. It distinguishes itself from sibling search tools like rcsb_search_fulltext, rcsb_search_by_attribute, and rcsb_search_by_structure by focusing on chemical components and their match types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's domain is clear from the first line, implying it is for chemical structure/formula queries, but it never explicitly contrasts with sibling tools or states when not to use it. While it references rcsb_search_by_attribute for attribute paths, it does not give when-to-use versus when-to-choose-another-tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior; the description adds meaningful context by explaining the MONDO resolution, optional pdb_entry_count annotation via annotation_lineage.id, and the exact return shape. It also points to resolver guidance for attribute path and lineage semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well structured with a purpose paragraph, usage guidance, Args, and Returns sections. Every sentence contributes meaning—no filler or redundant repetition of schema defaults.
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?
Given the resolver family context and the output schema being marked present, the description covers input semantics, expected return shape, and next-step guidance ('then search by it'). It is complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates: query defines free-text disease examples, limit explicitly says 'Max MONDO terms to return', and with_pdb_counts explains the default and what pdb_entry_count means. This is sufficient for an agent to populate all parameters correctly.
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 uses a specific verb 'Resolve' with a concrete resource: free-text disease terms to MONDO ontology IDs, explicitly framing the purpose as precise disease-based PDB searches instead of keyword guessing. This clearly distinguishes it from sibling fulltext report and other ontology resolver tools.
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?
The description gives explicit when-to-use guidance: 'Use for ANY request mentioning a disease/disorder/syndrome/condition' with concrete example phrasings. It contrasts with keyword guessing but does not name sibling alternatives or exclusions, so it falls just short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds context about its role as a resolver (returning InterPro entries) and the optional pdb_entry_count annotation. It does not dwell on auth or rate limits, which is acceptable given the strong annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear purpose statement, usage context, parameter definitions, and return shape. Every sentence contributes; no filler. The pointer to server instructions is concise and relevant.
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?
Given the moderate complexity, the description covers purpose, usage timing, parameters, and return format. It also references the resolver guidance for attribute path and lineage semantics, ensuring the agent knows how to proceed. The presence of an output schema further reduces the need to describe return values in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 0%, but the description's Args section fully compensates by defining each parameter: query as 'Free-text domain/family name', entry_type as 'Optional InterPro type filter', limit as 'Max entries', and with_pdb_counts as 'annotate each entry with pdb_entry_count'. This adds value beyond the schema's bare types/defaults.
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 explicitly states the tool 'Resolve a free-text protein domain, family, or fold ... to InterPro entries', with specific examples (SH2 domain, zinc finger). It clearly differentiates itself from sibling resolver tools like rcsb_find_go_terms and rcsb_find_enzyme_classes by focusing on protein domains/families/folds.
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?
The description gives explicit when-to-use guidance: 'Use this whenever a request references a protein DOMAIN, FAMILY, or fold', with concrete phrasings. It also contrasts with keyword guessing and points to resolver guidance in server instructions for precise search integration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond these: pdb_entry_count includes descendants via taxonomy_lineage.id, and with_pdb_counts 'disambiguates a species from its strains'. It also hints at an 'id-typing gotcha'. While it does not mention rate limits or auth, for a read-only resolver this is sufficient context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose, usage, args, returns. It is front-loaded with the core action and examples. Every sentence contributes value, including the resolver guidance pointer. No redundant fluff; the length is appropriate for a tool with nuanced behavior.
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?
The description includes a Returns section that matches the output schema, explains the resolver workflow, and covers the three parameters. Given the tool's moderate complexity and the presence of annotations, this description is complete. It even tells the user where to find additional resolver guidance, making it self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates. Each parameter is explained with examples: query as free-text organism/clade, limit as max taxa, and with_pdb_counts with detailed semantics (annotating pdb_entry_count and disambiguation). This adds far more meaning than the bare schema types and defaults.
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 and resource: 'Resolve a free-text organism, common name, or clade ... to NCBI Taxonomy ids'. It clearly distinguishes this from sibling search tools by emphasizing 'for precise taxonomy-based PDB searches instead of keyword guessing' and provides concrete examples. Purpose is unmistakable and well-scoped.
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?
It explicitly states when to use: 'Use when a request restricts structures by SOURCE ORGANISM or any higher taxon' and contrasts with a 'plain name search' that cannot expand clades. It also provides a workflow: 'Resolve the phrase to a taxon id here, then search by it' and points to server instructions for attribute path and lineage semantics. This is strong, actionable usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as readOnly, idempotent, openWorld, and non-destructive. The description goes beyond these hints by explaining the default return fields (entry/entity/chain identifiers, bound component id, author seq id), how unknown IDs are handled ('returned under not_found'), and the behavior of the 'fields' parameter as a GraphQL selection replacing the default. This is rich behavioral detail that complements the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it leads with the primary action in the first sentence, then provides default field context, and ends with a clear Args section. Despite being informative, every sentence earns its place by adding either purpose, parameter meaning, or usage guidance. No waste or redundancy.
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?
Given that the tool has an output schema (covering return structure) and strong annotations (readOnly, idempotent, openWorld), the description adds exactly the needed context: default fields, error behavior, and how to customize output. It even references rcsb_describe_data_object for further schema discovery, making the description highly complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero descriptions, but the description fully compensates by explaining both parameters: instance_ids is defined as 'entry.asym_id' with an example and error handling, and fields is described as an optional GraphQL selection with an example path and a pointer to a discovery tool. This gives the agent complete semantic understanding of each parameter.
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 and resource: 'Fetch non-polymer entity instances (individual bound ligands)', backed by a concrete example ('4HHB.E'). This clearly identifies the tool's function and distinguishes it from sibling tools like rcsb_get_nonpolymer_entities, which fetch entity-level data rather than instances.
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?
The description provides clear context for when to use the tool (to retrieve individual ligand instances) and what the default fields return. It also points users to rcsb_describe_data_object for verifying custom field paths, which is helpful guidance. However, it does not explicitly state exclusions or name alternative tools, stopping short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with readOnlyHint, openWorldHint, and idempotentHint already declared, the description adds meaningful behavioral detail: default fields are curated for a functional snapshot, heavier annotation sets can run to hundreds of entries and are deliberately kept out of defaults, and the `fields` parameter replaces the curated default. This goes well beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then organized into default vs. optional field behavior, then a clear Args block. Every sentence adds value—no filler or repetition of schema/annotations.
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?
Given the tool is a single-record fetch with a relatively rich output schema, the description covers the important context: default fields, optional heavy annotations, and how to verify custom field paths. It even references server instructions for deeper context, making the tool self-sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility for parameter meaning. It explains `uniprot_id` as a UniProt accession with an example, and `fields` as an optional GraphQL selection with examples and a discovery path (`rcsb_describe_data_object("uniprot")`). This fully compensates for the schema's lack of descriptions.
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+resource: 'Fetch the UniProt record RCSB maps to an accession', which clearly distinguishes this from the many search- and entry-focused sibling tools. The example accession P69905 adds immediate concreteness.
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?
The description gives strong contextual guidance: it explains the default functional snapshot and when to opt into heavier annotation sets via the `fields` parameter. It does not explicitly name alternatives or when-not-to-use this tool, but the unique resource and clear access path make the intended usage unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, the description richly discloses behavior: return format, pagination via next_offset, all_hits constraints (ignores limit, cannot combine with offset, refused above 10000, ignored with facets), sort_by restrictions (only sortable attributes, rejects full-text and mol_definition), and grouping behavior. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly structured with an Args list and a Returns section. Every sentence provides essential information about a parameter or return behavior; there is no fluff. The purpose is front-loaded, and the labeled sections make it easy to scan.
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 tool with 14 parameters, an output schema, and complex behaviors (pagination, faceting, grouping, sorting, attribute filters), the description covers all necessary aspects: pattern syntax, pattern types, sequence types, return types, error conditions (e.g., mol_definition rejection), and exact return structure. It is fully self-contained modulo server-instruction references.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the main properties, but the description compensates fully by explaining every parameter with examples, defaults, valid values, and cross-parameter interactions (e.g., all_hits vs offset, group_by requiring return_type='polymer_entity'). This is exemplary compensation for sparse schema descriptions.
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+resource: 'Find polymers containing a short sequence motif (PROSITE / regex / simple).' This clearly distinguishes it from sibling tools like rcsb_search_by_sequence (full sequence) and rcsb_search_strucmotif (structure motif).
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?
The description provides clear context for when to use the tool (searching by sequence motif with specific pattern types and sequence types), but it does not explicitly name alternatives or state when not to use it. It references server instructions for related details, but lacks direct exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint/idempotentHint annotations by detailing pagination (next_offset), the all_hits behavior with its 10000-hit refusal and offset incompatibility, facets changing the return shape, grouping semantics, and sort_by restrictions (only SORTABLE attributes, full-text rejection). This extensive operational disclosure gives the agent a clear model of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place, given 15 parameters and complex behaviors. It is front-loaded with a one-line summary, then organized into Args and Returns sections, making it easily scannable. No filler or redundancy.
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 tool of this complexity, the description covers all major behaviors: return value shape, pagination, facets, grouping, sorting constraints, combined attribute filtering, and the all_hits edge case. While it defers to 'server instructions' for faceting/grouping notes, that is appropriate and does not leave the agent without necessary guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries full responsibility for explaining parameters, and it does so thoroughly. Every parameter is described with types, defaults, constraints, and examples (e.g., identity_cutoff '0.3 = 30%', limit '1-100', sort_by's exclusion of full-text attributes). It also references the AttributeFilter schema for the attributes parameter.
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 'Find PDB polymer entities similar to a given sequence (MMseqs2, BLAST-like)', clearly identifying the tool as a sequence similarity search over PDB polymer entities. This distinguishes it from sibling search tools like rcsb_search_by_structure, rcsb_search_by_chemical, and rcsb_search_by_seqmotif.
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?
The description clearly indicates this is for sequence-based searching and references related tools (rcsb_get_polymer_entities, rcsb_search_by_attribute, rcsb_list_pdb_search_attributes) for follow-up actions. It does not explicitly name alternatives for when not to use this tool, such as rcsb_search_by_seqmotif for short motifs, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations (readOnlyHint, idempotentHint, etc.), the description adds substantial behavioral detail: defaults for assembly/asym_id, mutual exclusivity, pagination via next_offset, all_hits constraints, ignoring facets, sort_by limitations, and the exact return format. It also flags edge cases such as refusing all_hits above 10000 and rejecting mol_definition for sort_by, making behavior fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place given 14 parameters. It is front-loaded with a single-sentence purpose, then organized into Args and Returns sections with clear formatting, and references external notes for advanced facets/grouping to avoid unnecessary bloat. This is appropriately concise for the tool's complexity.
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?
The description completely covers the tool's context: input details, defaults, mutually exclusive options, output structure (including facets alternative), pagination, sorting constraints, and references to related tools and server instructions. With an output schema present, it does not need to restate return types, but it still explains the shape of the result. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden and succeeds. Each parameter is explained beyond its name/title: entry_id gets an example, assembly_id/asym_id get mutual exclusivity and default behavior, limit/offset get ranges and pagination semantics, attributes get a nested filter structure example, and sort_by gets constraints. This fully compensates for the sparse schema.
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+resource: 'Find structures with a similar 3D shape to a reference PDB structure.' This clearly distinguishes it from sibling search tools like rcsb_search_by_sequence, rcsb_search_by_chemical, and rcsb_search_by_attribute by uniquely focusing on 3D shape similarity.
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?
The description gives clear context for when to use the tool (given a reference PDB structure for 3D shape similarity) and references alternatives for attribute filtering (rcsb_search_by_attribute). It does not explicitly state when NOT to use it (e.g., vs. sequence or chemical search), so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent hints, but the description adds valuable behavior: fields are verified against the live schema, depth limits, caching performance caveats, truncation behavior, and how narrowing works. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is tightly structured: clear summary, usage modes, parameter explanations, and return format. Every sentence adds value, no fluff, and it's front-loaded with the core purpose.
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 discovery tool with rich output schema, the description covers all necessary context: return structure (with field names and types), usage patterns, limitations (truncation, depth), and integration with sibling tools. Complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description fully compensates by explaining every parameter: object_key (which object), into (nested path), query (case-insensitive keyword matching), and max_depth (with examples for depths 1-3). Provides concrete examples for each.
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+resource: 'Discover the fields available on a Data API object, from the live GraphQL schema.' It clearly distinguishes itself from sibling rcsb_get_* tools by explaining it provides the fields to request in those tools, with no ambiguity.
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 says when to use: 'Use this to find exactly what to request in a rcsb_get_* tool's fields= argument.' It contrasts with default selections and provides two detailed usage modes (browse and search by keyword) with workflow examples, effectively guiding tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior, so the description adds context beyond that: every returned path is 'verified against the live schema' and therefore safe to pass to `fields=`. It also discloses that the schema bottoms out at 3 levels and that results may include `truncated` and `note` fields, giving the agent a clear model of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-structured with Args/Returns sections, and every sentence contributes new information. It front-loads the core purpose in the first sentence, uses a compact example to convey the workflow, and avoids repetition. The length is justified for a describe tool that must clarify its relationship to the seqcoord family.
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?
Given the tool's purpose as an introspection aid, the description fully covers behavior, parameters, return structure, and integration with sibling tools. It even notes the schema's small size and the max_depth required to flatten it fully. The output schema is already available, so the description correctly focuses on semantics rather than restating output definitions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden, and it does so excellently. It explains `object_key` as a root field with shared types, `into` with concrete examples, `query` as case-insensitive matching against path and description, and `max_depth` with its range and effect. This goes far beyond the schema's bare titles and enums.
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 'Discover the fields available on a Sequence Coordinates object', which is a specific verb+resource combination. It distinguishes itself from the sibling rcsb_describe_data_object by explicitly calling itself the 'Sequence Coordinates analogue' with the same shape, making the purpose unambiguous.
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?
The description explains when to use this tool: to find what else can be requested via the `fields=` argument of rcsb_seqcoord_* tools. It also provides concrete usage patterns (browsing, drilling with `into`, flattening with `max_depth`, filtering with `query`) and gives an example call with a follow-up to a sibling tool, which serves as both a use case and an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/openWorld annotations, the description discloses unknown-ID handling ('not_found'), the fact that fields replaces a curated default, and that component ids appear under a specific key. These are non-obvious behaviors not visible in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 100 words but communicates purpose, usage, and parameter semantics in a structured way. Each paragraph earns its place, with no filler.
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?
The description covers input formatting, output behavior (component ids, not_found), and how to proceed with related tools. With an output schema present, this is a complete self-contained guide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers only names and types; the description adds the 4-character code format, one-element list convention, examples, and GraphQL selection guidance with a discoverability pointer. This fully compensates for 0% schema coverage.
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 'Fetch metadata for one or more PDB entries' explicitly naming the verb, resource, and scope. It lists specific fields (title, method, resolution, size, dates, citation) and distinguishes itself from sibling rcsb_get_* tools by explaining how to drill from entry ids to entity/assembly ids.
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?
It gives explicit compose-to-call instructions for sibling tools ('polymer_entity_ids... -> "<ENTRY>_N"') and tells when to use the result with rcsb_describe_data_object to verify fields. This is clear context for when to use this tool vs the many rcsb_get_* alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, etc., but the description adds significant behavioral nuance: case-insensitive literal substring matching, multi-word adjacency caveat, the three match_mode outcomes (exact/none/all), and the meaning of `note` on no-match. This goes well beyond the structured hints and provides actionable expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage, then organized into Args and Returns sections. Every sentence contributes essential guidance, from matching semantics to return mode definitions. Despite length, it is efficient and free of redundancy.
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?
The tool is simple (2 optional params) but the description covers the full workflow: when to call, how to pass the query, what schemas exist, and exactly what the response contains. It even addresses the no-match case and directs users to server instructions for chemical search, making it self-sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does. For `query`, it explains keyword format, literal substring behavior, the single-keyword recommendation, and the phrase-matching pitfall. For `schema`, it enumerates known values with approximate attribute counts and describes what each catalog contains.
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-resource pair: 'Discover the RCSB PDB Search schema: attribute paths, value types, and operators.' It clearly identifies the tool as a catalog/lookup utility and distinguishes it from sibling search tools by instructing 'Call this FIRST' and referencing `rcsb_search_by_attribute` as the follow-up consumer.
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 explicit when-to-use guidance: 'Call this FIRST when a request resolves to a clear attribute and value but you don't know the exact path.' It also names the alternative tool (`rcsb_search_by_attribute`) and clarifies how the output feeds into other `rcsb_search_*` tools, plus separate guidance for the 'chemical' schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that rendering uses a fixed server-side template, that the response contains either a url or html never both, and that html is only a fallback to be written to a file. It also warns that a result_type/id mismatch resolves nothing and returns empty derived values, which goes beyond the annotations' readOnlyHint and idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured into purpose, invocation order, key fields, and return contract. Every section earns its place, and the most important operational guidance (call last, supply facts only, don't write HTML) is front-loaded.
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?
Given the tool's complexity and the rich nested schema, the description covers invocation order, input field semantics, failure modes, and the return contract (url vs html plus template_version). The output schema and sibling tool list supply the remaining structural context, making the description fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the top-level schema has 0% description coverage by the given signal, the description thoroughly explains the report fields: title, api_calls with verbatim editor objects, result_type semantics and matching constraints, results with evidence/grounds/interpretation, and data_usage. It adds critical non-obvious constraints such as passing the editor object VERBATIM and the failure mode for mismatched result_type.
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 opening sentence, 'Render a structure-search report as a styled, self-contained HTML page,' names the specific verb, resource, and output format. It is clearly differentiated from the sibling search/get tools by being the final rendering step rather than a data retrieval or search operation.
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?
The description explicitly instructs 'Call this LAST, after the searches and rcsb_get_* calls that produce the values shown in the report,' giving clear ordering guidance. It also tells the agent not to write HTML, not to rewrite returned content, and explains how to handle resolver/discovery tools without editor links.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description reveals critical behavioral traits: hits are IDs only and need batching into rcsb_get_entries, the per-hit score carries no biological meaning, all_hits is refused above 10000 hits, sort_by rejects full-text-only attributes, and nested boolean groups are unsupported. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place. It is front-loaded with the key guidance and example, followed by organized Args and Returns sections. For a 12-parameter tool, this level of detail is appropriate and free of fluff.
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?
The description provides complete operational context: a full return-structure breakdown, paging via next_offset, batching guidance, and notes on grouping/faceting. It also gives concrete examples for both multi-condition and single-condition use, making the tool fully usable without external lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates thoroughly. It explains every parameter (attributes, logical_operator, return_type, limit, offset, all_hits, group_by, group_by_ranking, chemical, facets, sort_by, sort_direction) with detail, including operator types, range objects, and the chemical service switch.
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 precise verb+resource statement: 'Search by one or more structured attribute conditions combined with a single AND/OR.' It clearly differentiates from rcsb_search_fulltext and includes a concrete multi-condition example, making the tool's purpose unambiguous.
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?
Explicit when-to-use guidance: 'preferred over rcsb_search_fulltext whenever the request resolves to clear attribute(s) and value(s).' It also states when to avoid keyword search for ordinary constraints and when to fall back to fulltext for biological concepts, plus a prerequisite call to rcsb_list_pdb_search_attributes for unknown paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly, idempotent, openWorld hints, and description adds far more: score is text-relevance not biological importance, matching spans ALL text annotations, all_hits limitations (ignores limit, can't combine with offset, refused above 10000), sort_by restrictions (only SORTABLE attributes). This adds significant behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is dense and front-loaded: purpose first, then usage guidance, then per-parameter args. It avoids repetition by referencing server instructions for faceting, grouping, and return types. Every sentence contributes actionable information, making it appropriately sized for a 14-parameter tool.
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 14 parameters, rich annotations, and an output schema, the description covers query syntax, paging, return types, limits, sorting, grouping, and return format ('hits are ids only — batch them into rcsb_get_entries'). It also explains the meaning of score and warns against misinterpreting relevance. The tool is fully specified for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description compensates fully. Every parameter is explained with operational detail: query syntax (quoting, prefix wildcard, AND/OR/NOT not boolean), attributes type, logical_operator, limit range, offset paging, all_hits behavior, chemical switch, facets, sort_by constraints, group_by semantics. This goes well beyond the schema's bare titles.
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+resource: 'Search the PDB by free-text keywords' with concrete examples ('CRISPR Cas9', 'hemoglobin'). It explicitly distinguishes itself from sibling tools: 'Best for broad or exploratory keyword lookups' and contrasts with rcsb_search_by_attribute, rcsb_search_by_sequence, etc.
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 explicit when-to-use and when-not-to-use guidance: 'When a request has NO keyword (only attributes), use rcsb_search_by_attribute'; 'prefer structured search'; 'For a sequence, structure, chemical or motif match, use the matching rcsb_search_by_* tool'. Also advises resolving biological concepts to ontology IDs. This is exemplary alternative selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides rich behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint): it warns that author residue numbers give wrong/no hits, explains the all_hits behavior for explicit ALL requests, notes pagination with next_offset, and specifies sort_by restrictions (only sortable attributes, mol_definition rejected). This goes far beyond the static annotations and helps the agent anticipate edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into purpose, differences, Args, and Returns, and every sentence adds value. It is long due to 19 parameters, but avoids redundancy and uses efficient formatting (bold labels, examples, inline cautions). No fluff or repetition of schema defaults that are already visible.
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?
Given the tool's high complexity (19 parameters, no schema descriptions, subtle return types), the description is exhaustive. It covers all parameters, provides return format details (including the facets variant), and warns about pitfalls like author numbering and sort restrictions. This is a complete standalone reference for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite a 0% schema description coverage, the description compensates thoroughly. It explains residue_ids format with a concrete example (enolase catalytic residues), defines tolerance units and defaults, details all_hits/limit/offset interaction, and clarifies attributes, facets, group_by, and sort_by semantics. This is exactly the compensation needed for an under-documented schema.
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 explicitly states the tool finds structures containing a 3D structural motif, defined as a geometric arrangement of specific residues. It clearly distinguishes this from rcsb_search_by_structure (whole-shape similarity) and rcsb_search_by_seqmotif (sequence pattern), making its unique role unambiguous.
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?
The description explicitly states when to use this tool ('catalytic triads, binding sites, metal-coordination geometries') and explicitly differentiates it from two sibling tools, naming them directly. It also provides practical guidance on resolving label vs author numbering, which is essential context for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context beyond annotations: explains output shape (target_alignments[].target_id), the ENTITY-level PDB ID requirement with examples, and the mapping semantics. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: summary, usage context, examples, and parameter breakdown. Every sentence adds value; the length is justified by the tool's complexity. Front-loaded with a clear purpose statement.
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?
Complex cross-database tool with 5 parameters and an output schema. The description covers ID formats, constraints (entity-level requirement), optional parameters, and return value structure. No missing critical information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates. It documents every parameter: query_id format per reference system, from_ref/to_ref enum behavior, seq_range as optional 1-based [begin, end], and fields as GraphQL selection override. It also provides example values for multiple systems.
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?
Description uses a specific verb ('Cross-reference') and resource ('sequence across PDB, UniProt, and NCBI'), clearly stating the tool's function and scope. It distinguishes itself from siblings by explicitly mentioning NCBI coverage, which is unique among the seqcoord tools.
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 explicit when-to-use guidance: 'This is the tool for "which X identifiers correspond to this sequence?" across databases — including NCBI.' It also contrasts with the RCSB Data API, telling agents to use this tool for NCBI mappings when the Data API only handles UniProt. Concrete examples further clarify use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![rcsb-mcp MCP server](https://glama.ai/mcp/servers/rcsb/rcsb-mcp/badges/card.svg)](https://glama.ai/mcp/servers/rcsb/rcsb-mcp)

Score Badge

Copy to your README.md:

[![rcsb-mcp MCP server](https://glama.ai/mcp/servers/rcsb/rcsb-mcp/badges/score.svg)](https://glama.ai/mcp/servers/rcsb/rcsb-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rcsb/rcsb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server