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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context beyond that: the data is aggregated from multiple PDBe-KB partner resources and the response includes annotation type, per-residue scores, confidence metrics, group labels, and source URLs. It does not mention response size or pagination for large residue-level payloads, which is a notable gap for a multi-resource aggregation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that puts the operation and scope first and then the returned data. The enumeration of return fields is long but earns its place because there is no output schema; no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates well by describing the returned fields and their origin. Both required parameters are covered by the schema, and the read-only nature is carried by annotations, leaving nothing critical an agent needs in order to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description mentions only the entity ID and never references pdb_id, so it adds essentially nothing about how the two parameters combine or constrain the result set.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns residue-level functional and biophysical annotations for a specified PDB Entity ID') and enumerates the kinds of annotations (SASA, hydrophobicity, disorder, flexibility, EM local resolution), which distinguishes it from siblings like sec_struct, var, and doms that also key off entity_id.

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

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

Use is only implied by the purpose: call it with a PDB and entity ID when you want aggregated partner-resource annotations. There is no explicit when-to-use/when-not guidance and no sibling alternative named (e.g., when to prefer var or sec_struct for a single annotation type).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds substantive behavioral content the annotations lack, including the full set of returned fields (molecular weight, entity types/names, chain mappings, copy counts) and the important caveat that in_chains contains struct_asym_id values rather than author chain IDs. That caveat prevents a real misinterpretation and goes well beyond the annotation surface.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the operation and scope, followed by the return-field enumeration. Dense but every clause carries information; the parenthetical caveat is well placed rather than buried at the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must carry return-value semantics, and it does so thoroughly, enumerating each field reported per assembly. The remaining gap is behavioral scale detail — no mention of response size, pagination, or behavior for PDB IDs lacking assemblies — which is minor for a read-only single-parameter endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter and 100% schema description coverage, the schema already documents pdb_id as a 4-character PDB id code. The description only restates 'specified PDB ID' without adding format, validation, or edge-case guidance, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource: 'Returns information for all assemblies of a specified PDB ID', then narrows to per-entity detail within each biological or author-defined assembly. The resource (assemblies) is distinct from sibling tools that cover chains, molecules, or interfaces, though no sibling is named explicitly.

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

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

Usage is implied by the resource scope — call it when you need assembly composition for a PDB entry — but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as the chains or molecules endpoints. An agent must infer the selection condition from the tool name and description alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by stating the selection criterion (largest number of observed residues) and that chains are non-overlapping, but says nothing about ordering, determinism (despite idempotentHint=false), or what happens when no structures exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence with no filler, and the selection criterion is front-loaded within it. Nothing could be removed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter, no output schema and read-only annotations, the description is nearly sufficient: it conveys the input, the nature of the returned list and the optimization criterion. It falls short only on return shape details (per-chain coverage figures, ordering, empty-result behavior).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter exists and schema coverage is 100%, so the baseline is 3. The description repeats that the accession is the input but adds no format guidance (e.g. canonical accession vs isoform), so it does not improve on the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Retrieve'), resource ('list of non-overlapping PDB chains') and scope ('for a given UniProt accession'), which is clear. It does not explicitly distinguish itself from the sibling ebi-pdbe-best_soubsu_acc_11b902cf, whose differing overlap policy is only implied by 'non-overlapping'.

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

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

Usage is implied: an agent can infer this is the tool for picking representative structural coverage of a protein. There is no explicit when-to-use statement, no exclusions, and no routing to alternatives such as the other 'best' variant or the unip_map/chains sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, so safety is covered. The description adds substantive context beyond that: the ranking basis (data quality, model quality, resolution) and the full shape of each returned entry, which is real behavioral value. It could still note that rankings may shift over time (consistent with idempotentHint=false) and where results are truncated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the operation and ranking rationale, followed by the field inventory. The second sentence is a dense enumeration, but every listed field genuinely helps the agent understand the payload since no output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing the return and does so thoroughly (method, taxonomy, resolution, IDs, alignment segments, coverage). For a one-parameter lookup tool this is nearly complete; only result count, ordering direction, and pagination behavior are unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter and schema description coverage is 100%, so the schema fully documents 'uniprot_accession'. The description only re-states that the accession is the mapping key and adds no format, validation, or alternative-input detail, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource: a ranked list of PDB structures mapped to a UniProt accession, ranked by a named internal quality score. An agent knows precisely what it returns, though it never distinguishes itself from close siblings such as best_nosoubnosu_acc or unip_map, so differentiation is left to inference.

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

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

There is no explicit when-to-use guidance, no stated prerequisites, and no mention of alternatives. The phrase 'mapped to the given UniProt accession' implies the input context but leaves the agent to guess why it would pick this over best_nosoubnosu_acc or unip_map.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuine context beyond that: the data is ARPEGGIO-derived and the residue grouping is keyed by Bound Molecule ID. It says nothing about pagination, empty-result behaviour, or whether the entity must be a polymer, which are the remaining behavioural gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose and then the payload detail. It is slightly dense with metadata field names, but every clause carries information about what comes back, and there is no filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the return-value burden, and it does so reasonably: it names the metadata fields, the per-ligand CCD ID and name, and the residue grouping structure. For a two-parameter read-only lookup this is close to sufficient; only the response envelope and empty-case behaviour are unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters, and the schema already documents the 4-character PDB id and the mmcif molecule-number semantics of entity_id, including a numeric pattern. The description adds no further meaning about either parameter, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it returns ligand-binding site annotations for a specified PDB entity, and it enumerates the payload (Best Chain ID, Scaffold ID, interacting residue counts, CCD ID, name, residues grouped by Bound Molecule ID). That is far more concrete than a restatement of the name. It does not, however, distinguish itself from near-neighbours such as comp_intx, ligand-interactions, or bound_molecules, so an agent must infer the boundary.

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

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

There is no when-to-use guidance, no when-not-to-use, and no named alternative. The description never says to prefer this endpoint over ligand-interactions or comp_intx when the goal is per-entity binding-site detail, nor does it state prerequisites such as needing a valid entity_id from a prior chains/molecules call.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, idempotentHint=false), and the description adds genuine context beyond them: results are computed for the preferred assembly, the interaction categories enumerated (covalent, hydrogen-bond, polar, van der Waals, hydrophobic, atom-plane), and the exact meaning of the internal connectivity notation. It does not discuss pagination or response size, but for a read-only lookup that is a minor omission.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that leads with the return content and then qualifies it; every clause carries information. It is dense with parenthetical examples, which slightly hurts scannability but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the return-value burden, and it does so thoroughly by naming the three content blocks and giving a concrete notation example. It stops short of describing the actual response shape or field names, which leaves a small gap for a two-parameter data-returning tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, and the description only adds a bm_id example ('bm1') and the 4-character PDB id format implicitly. The residue-number/chain-id example illustrates output content rather than parameter semantics, so no real lift over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Returns') and precisely enumerates the resource content: composition, internal connectivity between covalently linked ligands, and detected interactions for one Bound Molecule ID of a PDB entry. The detail about CCD IDs and the ["F1","F6"] connectivity format clearly separates it from the sibling bound_molecules listing tool and from the hetcode-based interaction tools.

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

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

Usage is only implied: the reader must infer that this is the drill-down after obtaining a bm_id, and that hint lives in the input schema rather than the description. No alternatives (e.g., bound_molecules, comp_intx_comp_intx_hetcode) are named and there are no when-not conditions.

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

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

Annotations already establish this is a safe, non-destructive read (readOnlyHint=true, destructiveHint=false), so the safety profile is covered. The description does real work beyond that by disclosing the return payload in detail: Bound Molecule IDs like 'bm1', composition as covalently bound ligands with unique CCD IDs, and a concrete connectivity example ([“F1”,“F6”] meaning author_residue_number 1 and 6 in chain F are covalently bound). Annotations declare idempotentHint=false for what looks like a pure read, and the description neither explains nor contradicts that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The scope statement is front-loaded in the first clause, and the second sentence is dense with useful specifics rather than filler. It is slightly long and the nested parenthetical examples take effort to parse, but every clause conveys substantive content about the returned structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description bears the burden of explaining return values, and it does so well by naming the key fields and giving a worked connectivity example. The main remaining gap is behavior on an invalid or obsolete PDB ID and whether results are ever paginated or empty, which the agent cannot determine from this definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is only one parameter, whose '4-character PDB id code' format is fully documented in the schema. The description adds only the framing 'for a given PDB entry ID,' which conveys nothing the schema does not. The baseline of 3 applies when the schema already carries the parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Returns information for all bound molecules for a given PDB entry ID, including carbohydrate polymers.' An agent knows exactly what subset of PDB data this yields. It stops short of 5 because it never names or contrasts the closely related siblings (bound_mibmiib, ligand_monomers, comp_in, ligand_sum), which all sound like ligand/bound-molecule lookups.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives, despite roughly a dozen ligand-related sibling tools in the same server. The only hint is the phrase 'including carbohydrate polymers,' which implies a broader scope than a plain ligand list, but the agent must infer this. With this many near-duplicate ligand tools, the absence of routing guidance is a substantive gap.

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

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

Adds meaningful behavior beyond the annotations: the host routes each result to an existing viewer or a new one, the normalized builder is returned in structuredContent for follow-ups, full MVSJ is delivered to the App with download support, and compilation does not verify biological claims or coordinate availability. Annotations already cover the read-only safety profile, and the description respects that while adding viewer-routing and output-channel behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence front-loads purpose and input expectations, then the middle covers capability scope and the closing covers return/behavior caveats, so the structure is logical. It is dense and long with a capability list that borders on a dump, but nearly every sentence carries a rule or constraint an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a very large nested schema, no output schema, and a single required parameter, the description covers what the input must contain, what comes back (structuredContent builder plus MVSJ download to the App), what is prohibited, and what the tool does not guarantee. Remaining gaps are the unmentioned version param and the unspecified conditions under which results route to an existing versus new viewer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema's own description coverage is 0%, so the description carries the burden and does so for the 'builder' param by specifying it must be a complete specification, listing supported capability axes (chains, residue ranges, ligand instances, representations, colors, opacity, annotations, labels, tooltips, focus, camera, isosurfaces, clipping, transforms, MolQL selectors), and flagging placement rules like component opacity living inside representation.opacity. The 'version' parameter is never mentioned, which keeps this from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: 'Build a custom single-scene molecular visualization with MolViewSpec and open it in Mol* 5.13.1.' The word 'single-scene' implicitly separates it from the sibling build_mvs_story (multi-scene stories), though that sibling is never named explicitly, so the differentiation relies on inference.

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

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

Gives real operating rules: supply a complete builder spec including existing choices for follow-ups, ground selections in PDBe data, use label_seq_id for polymer residues vs auth_seq_id plus insertion code for non-polymers, and note that water is excluded unless include_water=true. It also sets a hard boundary ('No raw MVS trees, executable code or PyMOL text') and a workflow rule ('do not rebuild while waiting for viewer loading'), but never says when to pick this over build_mvs_story or other visualization siblings.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered; the description then adds real behavioral context: it emits one native multi-state MVSJ with timed playback, navigation and download, the host may update the originating viewer or open a new result, and defaults are 6500 ms/scene with 1500 ms camera transitions. It also discloses a limitation beyond annotations — 'Compilation does not establish coordinate availability or verify biological claims' — which is exactly the kind of trust-boundary information only prose can supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, scene-count constraint and the sibling schema reference, then moves to constraints, output, defaults and error handling in a logical order. It is on the long side at roughly nine sentences, and the Mol* version pin and the 'never directly on a component' warning slightly duplicate schema-level statements, but almost every sentence carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Against an extremely deep nested schema and no output schema, the description supplies the missing return contract (single MVSJ with playback/navigation/download), the host-side outcome, timing defaults, an evidence-grounding requirement, and a retry policy — enough to call the tool correctly. The remaining gap is that 'Ground all narrative claims and selections in PDBe evidence' is stated as a principle without indicating how evidence is supplied or validated within the input.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is reported as 0%, so the description must compensate, and it largely does: it defines the required scene shape (unique id, title, description, complete builder spec), cross-references build_mvs for the builder schema, and pins down two semantics the schema does not state — opacity must live in representation.opacity rather than on the component, and the default durations for scene and camera transition. It still doesn't cover the story-level version field or the parallel surfaces (annotations, primitives, volumes) beyond the pointer to build_mvs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and artifact ('Build a guided molecular story'), quantifies the scope ('2–20 ordered scenes'), names the renderer/host ('open it in Mol* 5.13.1'), and explicitly positions itself relative to the sibling build_mvs ('using the same schema as build_mvs'). An agent can distinguish this from build_mvs and from the structure-inspection siblings without opening the schema.

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

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

Gives clear operational context: use it when a multi-scene narrative is needed and reuse the scene schema from build_mvs, plus explicit stop and retry rules ('Stop after a compiled result', 'On validation failure, correct the input and retry once; never repeat identical input'). It does not, however, state an explicit exclusion such as 'for a single static view, use build_mvs instead' — the split is implied by scene count rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description adds genuine context: it discloses the response contents and flags an important interpretation trap, that chainId in additionalData is struct_asym_id rather than auth_asym_id. That identifier-semantics warning is real behavioral value beyond structured fields, though idempotency and error behavior are not addressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence states the return payload first, then appends the chainId caveat where it is most relevant. It is dense but every clause carries information; only the parenthetical could be split out for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the burden of describing returns, and it does so with reasonable specificity (chains, residue ranges, validation, metadata, identifier caveat). Missing are failure modes and whether the result is nested per-chain, but for a two-parameter read tool this is close to complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both pdb_id and entity_id documented in the schema, so the baseline is 3. The description restates that the tool keys on a PDB Entity ID but adds no format, range, or edge-case detail (e.g., what happens with an entity that has no polymer chains) beyond what the schema supplies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('Returns detailed chain-level annotations for a specified PDB Entity ID') and enumerates the payload (polymer chains, residue ranges, per-residue validation, Best Chain ID, author chain identifiers). This clearly distinguishes it in kind from entity-level siblings like sec_struct or bind_sites, though it never names or contrasts any of them.

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

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

Usage is only implied by the stated scope: an agent can infer it applies when it needs chain-level rather than entity-level or residue-level data. There is no explicit when-to-use statement, no prerequisites, and no routing guidance versus the many other 'ent_*' entity tools.

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

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

Beyond the readOnly/openWorld/non-destructive annotations, the description discloses a crucial negative capability: the viewer applies PDBe's transforms and no additional fitting, RMSD, per-residue displacement or inferred binding sites are computed. That prevents an agent from promising analyses the tool does not perform, and the opt-in behavior of ligands/annotations is also spelled out.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with purpose then prerequisites then behavioral caveats, with no filler. The middle sentence about opt-in data and workspace controls is slightly dense but every clause carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter comparison tool with no output schema, the description covers inputs, prerequisites, what is rendered (PDBe/SIFTS correspondence, CSV export) and what is explicitly not computed. The only minor omission is guidance on what the returned correspondence structure looks like, though the CSV export mention partially covers output expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 75% schema coverage the schema already documents chain IDs, segment_index and the two booleans; the description still adds meaning by framing include_ligands/include_annotations as opt-in supplied data and uniprot_accession/segment as conditionally required when mappings or segments are ambiguous. It does not add format or case-sensitivity detail beyond what the schema carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Compare two protein label chains') and names the exact mechanism ('PDBe's precomputed superposition matrices and SIFTS residue correspondence'), which distinguishes it from neighboring tools like comp_intx_proteins or comp_similarity that operate on ligands or interactions rather than chain superposition.

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

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

Prerequisites are stated plainly: a shared UniProt accession and a PDBe segment covering both chains, with the note that the aligned proteins are opened first and ligands/annotations must be opted into. It stops short of naming a sibling alternative or an explicit 'do not use this for X' exclusion, so it lands at a strong 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so safety is covered structurally. The description adds genuine behavioral context by saying the result includes entries where the component is standalone OR embedded in a larger entity, but says nothing about result size, pagination, ordering, or behavior for an unknown hetcode.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and result type, then the scope qualifier. Nothing is wasted, though the second sentence could be folded into the first without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only lookup with no output schema, the description covers what is returned (a list of PDB entries) and the inclusion rule. Only pagination/bounding and empty-result behavior are missing, which are minor for this tool class.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter's own description is circular ('Hetcode for the compound'). The description does add that the hetcode is a chemical component as defined in the PDB Chemical Component Dictionary, which clarifies the identifier namespace, but it gives no format or example values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'returns a list of PDB entries that contain the given chemical component'. It also scopes the semantics (standalone component vs. part of a larger entity), which separates it from a plain structure lookup. It does not name or differentiate against the many related hetcode siblings (ligand_sum, comp_intx, similar_ligands), so it stops short of a 5.

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

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

Usage is only implied: an agent holding a hetcode who wants the PDB entries containing it. There is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives such as the ligand summary or interaction tools that also take a hetcode. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value by explaining that counts are aggregated across all PDB structures and grouped by interaction type, but it says nothing about response size, pagination, or whether the aggregation scope can be narrowed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with no filler, and the core purpose is front-loaded ahead of the description of the returned data. Nothing is repeated and nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because there is no output schema, the description must convey the return shape, and it does so reasonably well by describing per-residue frequencies grouped by interaction type. What remains missing is the aggregation granularity, e.g., whether counts are global per PDB or normalized, which matters for interpreting results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With one parameter at 100% schema description coverage, the schema already documents the required 'hetcode'. The description only adds that a hetcode identifies a 'chemical component', which clarifies the concept but gives no format or lookup details (e.g., where to obtain a valid hetcode).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Returns aggregated interaction counts for protein-ligand interactions') and names the scoping input ('derived from all PDB structures containing the given chemical component'). It is clear what the tool returns, but it never distinguishes itself from siblings such as ebi-pdbe-ligand-interactions or ebi-pdbe-comp_in_comp_in_hetcode, which an agent could easily confuse with it.

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

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

There is no guidance on when to choose this tool over the many hetcode-based siblings (ligand_sum, comp_in, comp_intx_proteins), nor any stated prerequisites. The agent must infer selection purely from the resource named in the purpose sentence.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: only UniProt-mapped chains are returned and the output carries associated UniProt metadata. It says nothing about result cardinality, ordering, or what happens with an unknown hetcode, and idempotentHint=false is left unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. It is dense but every clause (interaction, PDB entries, UniProt mapping, UniProt metadata) carries distinct meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry more of the return-value burden, and it does partially by stating that UniProt metadata is included. However, it omits the shape of the response, whether multiple chains/entries per component are returned, and any pagination or empty-result behavior, which matters for a lookup tool keyed on one identifier.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single hetcode parameter, so the schema already documents it (albeit redundantly). The description adds modest meaning by framing hetcode as a chemical component identifier whose interacting partners are looked up; no format examples or validation rules are given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Returns') and a precise resource: protein chains in PDB entries that interact with a given chemical component, restricted to those mapped to UniProt. That scope restriction is distinctive enough to separate it from the rather generically named sibling comp_intx_comp_intx_hetcode, though the sibling is never named explicitly.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative tool is referenced. An agent must infer from the phrase 'mapped to UniProt' that results exclude non-UniProt-mapped chains, and must guess how this differs from the sibling comp_intx tool that also takes a hetcode.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the shape of the response: ligand names, functional annotation categories, and occurrence counts broken down by PDB entries, chains, and ligand instances, which is meaningful because no output schema exists. It does not explain the odd idempotentHint=false on a read-only aggregate, nor whether the aggregation spans all entries or a filtered subset.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the purpose and followed by the return contents; there is no filler. Slightly more verbose than strictly needed, but every clause conveys substance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only aggregation tool with no output schema, the description covers what is returned and in what dimensions, which is the main gap such tools usually leave. Missing pieces are minor: identifier format and whether 'occurrence counts' can be filtered or aggregated at different levels.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter and the schema description coverage is 100%, so the baseline is 3. The description adds no syntax or format detail for 'pdb_complex_id' beyond what the schema already states, leaving the expected identifier format to inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: 'Retrieve an aggregated summary of small-molecule ligands observed across different structural instances of a given macromolecular complex.' It also spells out what the summary contains (ligand names, functional annotations, occurrence counts). It stops short of naming which sibling to use instead, e.g. 'ebi-pdbe-ligand_sum_comp_sum_hetcode' or 'ebi-pdbe-bound_molecules', so the agent must infer positioning among the many ligand-related siblings.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named despite a crowded set of ligand-centric siblings. The scope phrase 'for a given macromolecular complex' implies context, but an agent cannot tell from this text whether to pick this over the ligand summary or bound molecules tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond annotations: some identifier types are one-to-many, and result richness varies by id_type. It does not describe pagination or result limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the purpose and followed by the key behavioral caveat. The enumeration of returned fields is justified because there is no output schema, and no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description responsibly enumerates the returned content and covers multi-match behavior and identifier-type tradeoffs. It could be slightly more complete by mentioning pagination or any result-size limits, but it is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining that id_type affects result cardinality and annotation richness—behavior not evident from the schema's flat list of four allowed values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Retrieve) and resource (information about macromolecular complexes) and enumerates the content covered (participants, stoichiometry, symmetry, etc.). It does not explicitly distinguish itself from sibling complex_* tools such as complex_bmsc or complex_ppcpapc, so differentiation is left to the identifier-oriented name.

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

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

Provides meaningful usage context by warning that UniProt/Rfam accessions or PDB IDs can match multiple complexes, and steering users toward pdb_complex_id for richer results. It does not explicitly state when to use this tool over sibling complex tools, but the identifier-type guidance is actionable.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by enumerating what the payload contains (PDB Complex IDs, representative structures, relationship types, shared vs. additional participants), but says nothing about result size, ordering, or why idempotentHint is false for what appears to be a pure lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, zero filler, and the core verb+resource statement is front-loaded before the definitional detail. It could be tightened marginally, but every sentence contributes a distinct piece of information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description covers purpose, the subcomplex/supercomplex distinction, and the shape of the returned fields, which is close to sufficient. The remaining gap is operational detail such as expected result volume or how the complex ID is obtained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter, and schema description coverage is 100%, so the schema already carries the semantics of pdb_complex_id and the per-parameter baseline of 3 applies. The description slightly exceeds that by implicitly scoping the ID to a macromolecular complex whose composition drives the lookup, though it adds no format or provenance guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb ("Retrieve") with a specific resource ("related subcomplexes and supercomplexes") and then defines both terms, so an agent knows exactly what class of object comes back. It does not name or contrast any sibling tool (e.g., complex_details, bmsc, ppc/papc), which keeps it from a 5.

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

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

Usage is only implied by "based on macromolecular composition" and the single required PDB Complex ID: call this when you have a complex and want composition-related neighbours. There is no statement of when NOT to use it, no prerequisite (e.g., where the complex ID comes from), and no pointer to alternatives for other kinds of complex relationships.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, so safety is covered. The description usefully adds that results are computed by PISA, span multiple structural instances, and include 5th/95th percentile aggregates — behavioral context beyond the annotations. It does not cover error behavior for unknown IDs or result size.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, purpose front-loaded and the property enumeration kept in a single clause rather than a bullet dump. The field list is long but each item is informative about the return payload, which matters because no output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does a fair job of describing return fields and the percentile summary, which is the key completeness need here. It is still thin on input expectations (ID format) and on how this differs from adjacent complex-analysis endpoints in a large sibling set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single required parameter, so the schema already carries the parameter meaning. The description adds no syntax, format, or example for the PDB complex ID beyond what the schema states, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Retrieve') and a specific resource ('PISA-calculated structural and energetic properties for structural instances of a macromolecular complex'), and enumerates the concrete fields returned. It does not distinguish itself from sibling complex tools such as complex_details, complex_bmsc or complex_ic, so an agent cannot tell from the text alone which complex endpoint to pick.

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

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

There is no guidance on when to use this tool versus the many sibling complex endpoints (complex_details, complex_bmsc, complex_ic), no prerequisites, and no note on what a valid complex ID looks like. The agent must infer usage purely from the resource name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful content-level detail (domain boundaries, identifiers, names, Best Chain metadata) but says nothing about response shape, per-chain aggregation, or behavior when no domains are annotated. Note the annotations themselves set idempotentHint=false for what reads as a pure lookup, which the description does not clarify.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence that leads with the action and resource, then enumerates sources and metadata. The trailed enumeration is long but each clause adds informational value; there is no filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining returns, and it does list the returned categories. However, for a task that merges four domain databases plus chain metadata, it omits how the results are structured, whether all chains or only the best chain are reported, and what an empty result looks like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in structured form. The description only says 'specified PDB Entity ID' and adds no meaning beyond the schema — no explanation of how pdb_id scopes entity_id or that entity_id is a numeric molecule number. Baseline 3 applies when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a concrete verb+resource ("Returns sequence and structural domain annotations for a specified PDB Entity ID") and enumerates the contributing sources (CATH, SCOP 1.75, Pfam, InterPro) plus the Best Chain ID metadata. That makes the tool's scope far more specific than vague siblings, though it never explicitly contrasts itself with neighboring entity-level tools like sec_struct or annot.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives. An agent must infer from the word 'domain' whether to call this versus sec_struct, annot, or bind_sites, and nothing tells it that pdb_id and entity_id must be a valid pair or where entity_id comes from.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description only needs to add context. It does add one valuable clarification: chain_id is a label_asym_id. It does not explain the idempotentHint=false on what is semantically a pure lookup, nor the return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler; the resource, the scope, and the key identifier convention all land immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read with no output schema, the definition covers what is needed to invoke it correctly and identifies the identifier convention. The remaining minor gap is the return format (one-letter vs three-letter codes, plain text vs FASTA), which is not stated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema itself only says "PDB chain id." The description earns credit above the baseline by specifying that the chain identifier is label_asym_id, which resolves real ambiguity against auth_asym_id usage elsewhere in PDB APIs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Returns the amino-acid sequence") scoped to a specific PDB Entry and Chain ID, so the agent knows exactly what comes back. It does not differentiate itself from the many sibling sequence-style tools (seq_cescie_id, seq_cuuscu_acc, ent_chain_seq), leaving the agent to infer which sequence endpoint applies.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named despite a crowded set of sibling tools that also deal with sequences, chains, and entities. The only implicit guidance is that the caller must already know a pdb_id and chain_id.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description need only add context — which it does by describing the computational source (PISA) and the shape of the payload. It stops short of disclosing volume, pagination, or whether all interfaces are returned when no filter is given, which matters for a potentially large contact list; also idempotentHint=false is unexplained but not contradicted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose followed by return content and filtering options; no filler or repetition. It could be tightened slightly, but every sentence contributes information an agent would use.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return values and does so adequately at a field level (interaction types, distances, atoms and residues from both chains). The remaining gap is scale — nothing about result size or whether the call is paginated for a PDB entry with many interfaces.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter is already documented, so the baseline is 3; however the description adds real meaning by stating that assembly_id and interface_id are optional filters and that filtering narrows the returned contacts, which the schema text ('Numerical assembly id code', 'Index of interface, one based') does not convey on its own.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource — 'Returns all interface residue contacts calculated by PISA' — scoped to 'a specified PDB entry ID', and it enumerates the returned content (interaction types, distances, participating atoms/residues). It does not explicitly differentiate itself from the closest sibling, ebi-pdbe-iface_res_ent_interfaces_id_entity_id (entity-level interface residues), so an agent must infer the distinction from 'contacts' vs 'interfaces'.

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

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

Usage is only implied: the tool is for retrieving PISA-calculated contact detail for a PDB entry, and the sentence 'Results can optionally be filtered by assembly_id and interface_id' hints at when to supply the optional parameters. There is no explicit when-to-use / when-not-to-use guidance and no naming of alternatives such as the entity-level interface residues tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description nonetheless adds real behavioral context by disclosing that unmodelled residues are included, that waters are filtered out, and what per-residue details come back (numbering schemes, insertion codes, modelled-atom fraction, alternate conformers). It omits volume/size expectations and behavior for an unknown PDB id, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence states the operation first and then enumerates the return fields; every clause carries information and nothing is repeated from the title. The return-field list is long but each item is substantive, so it stays readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining the return shape and does so thoroughly for a one-parameter read tool, including the two numbering conventions and the modelling fraction. It lacks error/empty-result behavior and any sizing caveat for large entries, so it is not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single pdb_id parameter is fully documented in the schema (100% coverage, including the 4-character format requirement), so the description does no parameter work and none is needed. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 ('List all residues in a PDB entry') and immediately bounds the scope ('excluding waters, including both modelled and unmodelled residues'), which distinguishes it from a plain chain or entity listing. It does not explicitly name a sibling tool to contrast with, so it falls short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as the chain, entity, or interface-residue siblings. The only hint at a use case is implicit in the enumerated return fields (modelling fraction, alt conformers), which an agent must infer.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=false, and destructiveHint=false, so safety and mutation behavior are covered. The description adds useful detail about the returned resource fields, but does not discuss response shape, empty-result behavior, pagination, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one front-loaded sentence that immediately states the return type and target. The examples of origins, labels, evidence codes, dates, and URLs are useful but make the sentence somewhat long, without becoming structurally confusing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only lookup with one fully documented parameter and no output schema, the description explains the returned resource type and enumerates the main returned fields. It is nearly complete, though it could mention response format or error behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter is fully documented in the schema, including the 4-character PDB ID requirement. The description adds only that the lookup is for a PDB entry and does not provide additional format or constraint details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb and resource: it returns FunPDBe functional annotation resources for a given PDB entry. It also lists the kinds of fields returned, which helps distinguish it from generic annotation or entity tools, though it does not explicitly name a sibling alternative.

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

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

Usage is only implied by the phrase 'for a given PDB Entry' and by the tool's focus on FunPDBe functional annotation resources. There is no explicit guidance on when to prefer it over related PDB annotation tools, and no exclusions or prerequisites are stated.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the description's job is to add context — and it does: it discloses that content is pre-generated, that sections and abstract key points are returned, that inline reference markers are preserved, and that supporting PDBe source URLs and fields are listed. The important failure mode ("may not exist for every entry") is stated up front. It does not say what the miss looks like (empty result vs. error), leaving one behavioral gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, then usage, then return shape. The middle sentence is slightly dense (sections, abstract points, references, URLs, fields), but every clause carries information an agent needs. No filler or repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description properly compensates by describing what comes back: summary sections, an abstract, and linked source fields. The existence caveat handles the main failure mode. Only minor gaps remain (size of the payload, whether sections are always all present).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter and the schema documents it fully at 100% coverage, including the 4-character pattern and an example. The description's "four-character PDB entry" is consistent with the schema but adds nothing new. Baseline 3 is appropriate when schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: "Retrieve the pre-generated AI summary for a four-character PDB entry." That is unambiguous and implicitly separates it from the UniProt-keyed LLM summary sibling (llm_unip_sum_...) by scoping to a 4-character PDB ID. It stops short of naming any sibling explicitly, so it does not earn a 5.

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

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

"Use this for an entry overview instead of writing a new summary" gives a clear selection rule: prefer this tool over synthesizing an overview yourself. The caveat that a summary may not exist for every entry tells the agent what to expect on a miss. However, no sibling tool is named as an alternative (e.g. the UniProt-keyed summary tool), and there is no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that, the description usefully discloses that this is a schema-introspection call returning full detail for every edge type, and it supplies the expected output shape, which matters because there is no output schema. It stops short of stating result size or ordering guarantees, but the behavioral picture is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is well front-loaded, but the description is verbose: the bulleted field list is then repeated almost verbatim in the worked 'Expected Output Format' example. The example is genuinely useful given there is no output schema, but the duplication makes it longer than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only introspection tool with no output schema, the description covers everything an agent needs: what it returns, the exact field semantics, and a concrete example of the response format. Nothing required to call it correctly or interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the baseline this scores 4. The description correctly presents the call as unconditional and global over the whole schema, leaving no parameter semantics to clarify.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it retrieves metadata about all relationship types (edges) in the PDBe graph database schema, and it enumerates exactly what is returned (label, description, from/to node labels, properties). This clearly separates it from node-oriented siblings, but it never explicitly distinguishes itself from the closely related graph_nodes or graph_node_relationships tools by name.

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

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

Usage is only implied: the description says the tool can be used to 'understand the different types of relationships' and 'then... explore the graph more effectively by writing Cypher queries.' There is no explicit when-to-use versus when-not, and no direct pointer to graph_nodes, graph_indexes, or graph_example_queries as alternatives, so the agent must infer the routing itself.

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

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 covered. The description goes beyond that by disclosing the return shape: a list of example queries, each pairing a natural-language question with a Cypher query string, backed by a concrete output sample. It does not say how many examples are returned or whether they are curated/static, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, and the output-format block with a real query example is genuinely informative rather than filler. The second sentence largely restates the first ('This tool can be used to get sample queries...'), which is the one piece of waste in an otherwise tight description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must explain the return value, and it does so thoroughly via the 'Question:'/'Query:' format plus a full worked example. For a zero-parameter, read-only lookup tool that is essentially complete; only the absence of any note on how to use the returned queries (e.g., run them elsewhere) is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema carries no semantics to supplement; the baseline for a 0-parameter tool applies. The description correctly adds no parameter prose, and there is nothing misleading about invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: 'Retrieves example Cypher queries for exploring the PDBe (PDBe-KB) graph database.' It is clear this returns static sample queries rather than executing anything, which implicitly separates it from graph_nodes, graph_edges, and graph_node_relationships, but no sibling is named explicitly.

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

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

It states the tool 'can be used to get sample queries that demonstrate how to interact with the PDBe graph database,' which implies the use case of learning the graph model or bootstrapping a Cypher query. There is no explicit when-not guidance and no pointer to the actual query-execution or schema-inspection siblings, so an agent must infer the routing.

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

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

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered without the description. The description adds useful behavioral detail by spelling out the exact return format (Node/Property pairs per index) in the absence of an output schema. It does not mention result size, whether indexes include relationship indexes, or empty-result behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and use case are front-loaded in the first two sentences, and the output sample is directly informative given there is no output schema. Minor redundancy exists — 'returns detailed information about each index' restates the opening sentence, and the trailing parenthetical explaining that more indexes follow adds little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only metadata tool with no output schema, the description covers what an agent needs: what is returned and the shape of the result. It could go further by noting whether only node indexes are covered and how to pair this with example-query or node-listing siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies no inputs are needed, consistent with the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: retrieving metadata about all indexes in the PDBe Neo4j graph schema. It clearly frames the tool as schema-introspection rather than data retrieval, which distinguishes it in spirit from data-returning siblings. However, it never explicitly names the adjacent introspection siblings (search_schema, graph_nodes, graph_edges) to sharpen the boundary.

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

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

It states a concrete use case — understanding which node properties are indexed so Cypher queries can use indexes for performance. That is a clear when-to-use signal. It stops short of explicit alternatives or exclusions, e.g. directing the agent to search_schema for a broader schema overview or graph_example_queries for query patterns.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description still adds substantial behavior: per-label existence status, outgoing, incoming and self-loop pattern buckets, and a bidirectional note when the same relationship label appears in both directions. It even supplies a text output template, which is essential because there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with purpose and usage before enumerating return fields, and the bulleted structure plus fenced example makes the output contract scannable. The expected-output block is longer than strictly necessary, but it compensates for the absent output schema, so the length is largely justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter, no output schema, and simple read-only annotations, this description covers everything an agent needs: when to call it, exact label casing requirements, and the full shape of the response including the not-found case. No gaps remain that would cause a misinvocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter already documents exact, case-sensitive matching, so the baseline is a 3. The description earns an extra point by adding concrete example values (["Entry", "Entity", "UniProt"]) and confirming the input is a list processed per label, which clarifies expected cardinality and naming style.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource: verifies PDBe graph node labels and returns relationships connected to each label. That is clearly distinguishable from siblings like graph_nodes and graph_edges, which list schema elements rather than resolving label-to-label relationship patterns.

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

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

The description states the timing and intent explicitly: use it after inspecting the node and edge schema, once node labels have been chosen for a Cypher query, to confirm labels and relationship directions exist. It does not name graph_nodes or graph_edges as the specific alternative tools, so the routing is implied rather than spelled out.

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

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

The annotations already establish read-only, idempotent, non-destructive behavior, and the description goes further by describing exactly what comes back for every label: name, human-readable description, and property list with per-property descriptions. It doesn't mention result size, whether all labels are always returned, or any caching/rate limits, which keeps it shy of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded well, but the text repeats itself: 'This tool can be used to understand...' and 'This tool returns detailed information...' restate the opening sentence, and the bullet list of returned fields is then duplicated nearly verbatim in the worked output example. Trimming one of those two blocks would lose no information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must carry the return-value burden, and it does so with a concrete sample format that an agent can parse. What's missing is scope information (whether all labels are guaranteed to be present, and how the result relates to graph_edges/graph_node_relationships for a full schema picture).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning to add. The description's phrasing ('all node types', 'each node label') correctly signals that the tool is unfiltered and takes no arguments, which is consistent with the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Retrieves metadata about all node types (also known as "labels") defined in the PDBe (PDBe-KB) graph database schema.' The node-vs-edge distinction is implicit enough that an agent could separate this from graph_edges, but it never names graph_edges, graph_indexes, or search_schema, so sibling differentiation is not explicit.

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

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

It states a use case ('understand the different types of entities ... and then ... explore the graph more effectively by writing Cypher queries'), which gives the agent a reason to call it. However, it never says when to prefer this over the sibling schema tools like graph_edges, graph_node_relationships, graph_indexes, or search_schema, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description contributes beyond that by disclosing data provenance (PISA-detected contacts) and the shape of the returned payload (partner UniProt accession, name, residue ranges, Best Chain ID). It does not mention response format or size, but for a read-only lookup this is solid added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the core purpose is front-loaded before the return-payload detail. Every clause carries information an agent would otherwise have to guess at.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because there is no output schema, the description rightly spends its second sentence enumerating returned fields, which is exactly what an agent needs for this endpoint. The remaining gap is routing: with roughly fifty siblings including a near-identical ent_iface_res endpoint and several interface/complex tools, the description should say when this one is the right choice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both pdb_id and entity_id fully documented in the schema (including the mmcif 'molecule number' meaning of entity_id). The description restates the entity ID requirement but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns protein–protein interface annotations for a specified PDB Entity ID', and narrows scope to PISA-detected contacts. The entity-level focus is clear, but the description never distinguishes this endpoint from the closely related sibling 'ebi-pdbe-ent_iface_res_ent_iface_res_id_e3f93cbf', leaving the agent to infer which interface-residue endpoint to pick.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The only usage signal is implicit: the caller must already have a PDB ID plus entity ID, which suggests post-identification drill-down, but that inference is left entirely to the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description usefully discloses the shape of the result (per-category counts, outliers, percentages, RMSZ values) and the null-percentage behavior for categories with no residues, which is meaningful because no output schema exists. It does not clarify the unusual idempotentHint=false or error behavior for invalid PDB IDs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the summary purpose and then enumerates the returned metrics compactly. The bullet-style list is efficient, though the category examples could be trimmed or the null-handling note moved after the core enumeration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with no output schema, the description does a fair job explaining what is returned. However, it omits usage differentiation from the outliers sibling and any note about entry-existence or error behavior, leaving some context gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single pdb_id parameter, and the schema already documents the 4-character PDB id format. The description adds no additional meaning about the parameter, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it provides a validation summary of geometric and electron-density metrics. It is clear what the tool returns, but it never distinguishes itself from the sibling outlier tool (ebi-pdbe-outliers_val_outliers_all_id) or explains which validation view an agent should choose.

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

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

There is no when-to-use guidance, no prerequisites (e.g., entry must exist), and no mention of alternatives despite a sibling outliers tool that overlaps in scope. The agent is left to infer usage entirely from the purpose statement.

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

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

Annotations already establish readOnly/openWorld/non-destructive, yet the description adds real behavioral context beyond them: records are PDBe-supplied, distances and classifications are displayed without recalculation or reclassification, and contact lines are suppressed when atom/assembly mapping is ambiguous with a fallback to 'the table'. That conditional-suppression behavior is exactly the kind of disclosure an agent cannot get from annotations. It would be a 5 if it were clearer about what permissions or payload volume 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose then procedure, with no filler sentences. A few phrases ('supplied interaction records', 'use the table') are terse enough to be slightly ambiguous, but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With six parameters, no output schema, and no field documentation in the schema, the description carries most of the burden and does explain the two-phase flow and the content of returned records (classifications, distances, contact lines). Gaps remain: it references 'the table' without explaining it and never characterizes the shape or volume of the returned interaction list.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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, and it largely does: it explains that pdb_id triggers instance listing, and that auth_asym_id/auth_seq_id/comp_id/insertion_code together identify a specific instance, including that CCD and insertion code are optional ('when available'). Only label_asym_id is left entirely unexplained, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource — PDBe-reported ligand interactions for an exact ligand instance — and distinguishes itself from generic search tools by scoping to 'exact ligand instance'. However, it never explicitly names the closely related siblings (comp_intx_proteins, comp_intx_hetcode, ligand_sum), so the agent must infer the boundary from the two-step instance workflow.

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

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

It gives an explicit staged usage instruction: first call with a PDB ID to list instances, then supply author chain and author residue number (plus CCD and insertion code when available) to fetch that instance's records. That is clear sequencing guidance. It falls short of a 5 because it never states when NOT to use this tool or which sibling to pick instead for non-instance-level interaction data.

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

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

Annotations already declare this a non-destructive read, so the remaining burden is describing the payload, and the description does that well by enumerating the returned fields (molecular weight, chain, residue numbers, CCD IDs/names, entity IDs, conformer counts, bound molecule IDs, functional class). It does not cover ordering, pagination, or behavior when an entry has no ligands, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the long field enumeration is justified because no output schema exists to carry that information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lookup with no output schema, the description supplies the return-value content an agent needs to decide relevance. Missing only minor operational details such as empty-result behavior and result ordering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With one parameter at 100% schema description coverage, the schema already documents the 4-character PDB id. The description adds only the implicit notion that the id selects an entry's ligand set, which is marginal beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Returns') and a precisely scoped resource ('all modeled non-water ligand instances for a PDB entry'), which is enough to distinguish it from summary-style siblings such as ligand_sum or comp_in. It stops short of naming or contrasting any sibling explicitly.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. The 'non-water' qualifier hints at scope but is a data filter, not usage guidance, so an agent must infer the choice 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about returned fields and metrics, but it does not clarify result cardinality, pagination, error behavior, or why idempotentHint is false for a read-only query.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is two dense sentences with no filler, and the core purpose is front-loaded. The metric list is compact and the returned-entry details follow naturally.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must explain return values, and it lists metric families, location identifiers, and an outlier flag. However, it leaves ambiguity about whether the tool returns one ligand entry or multiple entries for the given chain/residue, and it does not mention limits or error cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents pdb_id, chain_id, and residue_number. The description does not add meaning beyond the schema for these parameters; it focuses on output content instead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the resource and scope: ligand-level validation results combining Mogul geometric analysis and experimental fit metrics. It is specific about the returned metrics and outlier flag, but it does not explicitly distinguish this tool from sibling ligand, outlier, or validation tools.

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

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

The description explains what the tool returns but gives no explicit guidance on when to use it versus alternatives such as ligand_sum or outliers. Usage is only implied by the mention of ligand validation results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, and the description usefully adds what the payload covers (identifiers, descriptors, synonyms, cross-references). It does not disclose response shape, size, or whether the summary is expensive or truncated, which matters for a broad summary endpoint with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero preamble, though the long comma-separated enumeration of content categories is somewhat list-heavy. Every clause is content-bearing; nothing is redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, describing the returned categories is the right compensation and is done here. However, for a summary tool with many hetcode-keyed siblings, the absence of any routing guidance or note on response granularity leaves a meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is exactly one parameter with 100% schema description coverage, so the baseline is 3. The description confirms 'hetcode' identifies the chemical component, but adds no format, casing, or validity detail (e.g., PDB three-letter codes) beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns a summary for the chemical component identified by a hetcode, and it enumerates the content categories (structure identifiers, physico-chemical descriptors, synonyms, metadata, functional annotations, cross-references). An agent knows what the tool does, but nothing distinguishes it from close siblings such as comp_intx_comp_intx_hetcode, comp_in_comp_in_hetcode, or similar_ligands_comp_similarity_hetcode, which also key off a hetcode.

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

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

There is no when-to-use guidance at all: no statement of what question this answers that the interaction or similarity tools do not, and no exclusions. The agent must infer from the name and sibling list which hetcode-keyed tool to pick.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description earns credit by disclosing the response shape (associated PDB structures, residue-level annotations) and the important caveat that residue start/end follow either UniProt or PDB numbering. It also enumerates annotation fields (provider, citations, entity type, textual evidence, annotator, confidence scores) that an agent would otherwise not know to expect. Minor gap: no mention of pagination, rate limits, or behavior for accessions with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the numbering caveat is well placed, but the final clause ('enabling comprehensive exploration of machine-predicted functional and structural insights') is filler that adds no decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the heavy lifting by enumerating what comes back—structures, residue ranges, provider, citations, evidence, confidence scores—which is enough for an agent to consume the result correctly. Only the absence of edge-case behavior (empty results, invalid accession handling) keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter with 100% schema description coverage, so the schema fully documents it. The description adds no format details for the accession (e.g., whether isoform suffixes are accepted), which matches the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 ('Retrieve text mined annotations for a given UniProt accession') and names the returned payload (PDB structures, residue-level annotations). It stops short of differentiating itself from the many UniProt/annotation siblings such as unip_gen_annot_unip_annot or annot_ent, so an agent cannot tell from the text alone which one to pick.

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

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

There is no statement of when this tool is the right choice versus alternatives, no prerequisites, and no exclusions. The closing phrase about 'comprehensive exploration of machine-predicted functional and structural insights' is aspirational rather than actionable routing guidance.

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

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

Annotations already flag a safe read, but the description adds context they do not carry: the caller is the App rather than the agent, a workspace must already be open (a state prerequisite), and the response contains annotation records and track layers rather than coordinates or a scene. That is meaningful behavioral disclosure beyond readOnlyHint/destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical negative guidance is front-loaded in the first sentence, and the remaining sentences progressively narrow the legitimate use case and output. It is information-dense with little waste, though the opening sentence is long and the 'already open workspace' point is restated slightly differently later.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter helper with no output schema, the description covers everything an agent needs: caller restriction, prerequisite state, sibling routing, and response contents. Nothing material about correct invocation is left ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema coverage, including a regex pattern and example (4hhb), so the schema fully documents it. The description adds nothing about pdb_id formatting or validity, which is acceptable given the coverage, leaving this at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource — loading optional PDBe-supplied residue annotations into an already-open workspace — and immediately contrasts it with the structure-opening path. It also states what the tool does not return (coordinates, MVS scene), which sharpens the boundary further.

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

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

It gives an explicit prohibition (never call in response to a user request to open, view, inspect, or show a structure, even by entry ID), an explicit alternative (ebi-pdbe-open_structure for every initial viewing request), and the one legitimate caller context (the App loading annotations into a workspace that is already open). When/when-not/alternative are all present.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the return shape ('mapped residue segments and associated annotations for each resource'), which is useful, but says nothing about pagination, size limits, or behavior for unmapped residues.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences, front-loaded with the core mapping capability and the resource list. No filler, though the second sentence packs query directions and return values without much structural separation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter, full schema coverage, and no output schema, the description covers purpose, accepted inputs, and return content adequately. Only the absence of guidance on result volume and sibling differentiation leaves a modest gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single required parameter, so the schema already enumerates accepted identifier types. The description adds little beyond that, and its mention of 'auth_asym_id or struct_asym_id' cannot be supplied through the one-parameter schema, which risks confusing the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('Provides unified SIFTS residue-level mappings between PDB protein chains... and all major sequence and domain resources') and enumerates the covered resources (UniProt, Pfam, InterPro, CATH, SCOP, GO, Ensembl, HMMER). It is clear what the tool returns, though it never names or contrasts with a sibling such as ebi-pdbe-unip_map_ent, which covers adjacent mapping ground.

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

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

It states both query directions are supported ('PDB-to-identifier and identifier-to-PDB'), which implies when the tool applies, but gives no explicit when-to-use/when-not guidance, no prerequisites, and no pointer to alternatives among the many mapping-oriented siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, but the description adds no behavioral context beyond the safety profile. It does not say what kinds of interactions are returned, how the ligand is identified, or what the response looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single sentence with little wasted wording, but "This call provides" is filler and the sentence is under-specified rather than front-loaded with useful detail. It is concise but not particularly informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter query tool with no output schema, the description is too thin: it does not explain interaction types, return format, or how the required pdb_id/chain_id/seq_id identify the bound ligand. An agent could attempt a call, but would lack context to interpret or trust the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents pdb_id, chain_id, seq_id, and preserve_case. The description adds no parameter meaning beyond that baseline, which is acceptable when the schema is fully covered but provides no extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that the tool provides interactions for a bound ligand in an entry, which gives a general resource and action. However, "interactions" is vague, the verb is generic, and it does not distinguish this tool from sibling tools such as ebi-pdbe-ligand-interactions or the comp_intx tools.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. An agent must infer its role entirely from the vague description and the tool name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. With no output schema, the enumerated field list (entity type, UniProt-mapped names, synonyms, sequence, chains, copy numbers, organism, ligand info) is genuinely useful disclosure of what comes back, but the description says nothing about 'summarised' depth, selective versus full retrieval, or why idempotentHint is false for an apparently read-only fetch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence that names the resource first and then the contents, with no filler or duplicated phrasing. The long semicolon-chained field inventory is dense but each item is substantive, though a short structured list would read better than one run-on clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only lookup with a simple two-parameter schema and no output schema, the field enumeration largely substitutes for return-value documentation. What is missing is the relationship between the required pdb_id and optional entity_id (all entities versus one), and any note about response size or shape when an entry contains many entities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both pdb_id and entity_id are documented in the schema. However, the description describes fetching 'each molecule' in an entry and never explains that the optional entity_id narrows the response to a single entity — a meaningful behavioral nuance the schema text does not convey beyond labelling it 'Entity id'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns summarised molecule/entity information for a given PDB entry, and clarifies the mmcif terminology ('entity'). It is clear what the tool produces, but it never distinguishes itself from close siblings such as ebi-pdbe-bound_molecules_bound_molecules_id_433acab7 or ebi-pdbe-chains_ent_chains_id_entity_id_200017f6, so the agent must infer the difference from names alone.

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

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

There is no when-to-use guidance, no exclusions, and no mention of any alternative tool in a sibling list packed with molecule-, chain-, and ligand-oriented endpoints. The only implied usage is 'fetch entity metadata for a PDB entry', which the agent could guess from the name.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered. The description adds behavior the annotations cannot: only the first coordinate model is displayed, the deposited asymmetric unit is the default, and the call is one-shot because the App loads coordinates asynchronously. It omits what happens on a failed or invalid accession, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the core action and scope, with no filler. The closing sentence is slightly redundant ("completes the viewing request" plus "let the App load coordinates"), but that redundancy reinforces an important one-shot behavior rather than wasting space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter viewer launcher with no output schema, the description covers purpose, default model/assembly selection, and the async completion contract an agent needs to avoid redundant calls. Nothing essential to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (including chain_id, assembly_id, include_ligands, include_annotations) are already documented. The description reinforces the assembly_id default ("defaults to the deposited asymmetric unit") but adds no format or interaction detail beyond the schema. Baseline 3 applies when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Open an experimental PDB structure in an interactive 3D viewer") and adds the follow-on capability (inspecting chains, ligand instances, residues). This clearly separates it from the many data-retrieval siblings, which return records rather than launch a viewer.

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

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

Gives an unusually explicit stopping rule: "A successful result completes the viewing request; stop calling this tool and let the App load coordinates." That is real when-to-use/when-to-stop guidance. It does not, however, contrast itself with adjacent tools such as load_structure_annotations or compare_structures, so the alternative-selection guidance is incomplete.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond them: results are grouped by category, atom/residue identities use unit-id notation, and a types_of_outliers section summarizes per-residue participation. It does not cover pagination or result size, hence not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose and then the return structure. It is slightly dense and has a missing sentence break between 'unit-id notation' and 'The types_of_outliers section', but no filler text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description supplies the essential return-shape information (grouping by category, unit-id notation, per-residue summary section) that would otherwise be missing. Only minor gaps remain, such as result volume or how to interpret outlier counts.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter with 100% schema description coverage, so the schema carries the meaning. The description adds nothing about pdb_id format or behavior, which fits the baseline of 3 for a fully documented single parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: lists MolProbity-detected geometric and model–data outliers for a structure. It enumerates the outlier categories (clashes, sidechains, RSRZ, bond/angle, RNA suite/pucker, chirality, planes, symmetry clashes) and the reporting units, which clearly separates it from sibling tools like key_val_stats or sec_struct.

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

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

Usage is implied: the agent can infer this is the validation/quality-check tool keyed by PDB id. However, there is no explicit statement of when to prefer it over other per-structure tools, no prerequisites, and no mention of alternatives or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds value by naming the return content (PDB entries, RNA chains, matched regions). However, it says nothing about result size, pagination, or the odd idempotentHint=false on what appears to be a pure lookup, and does not explain what happens when the accession matches nothing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler, and the return content is stated before any nuance. It earns its place but is minimal; the string is essentially identical to the tool title, so the description contributes no framing beyond the annotation title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only tool with no output schema, the description adequately says what comes back, which is the main thing an agent needs. It is still thin on the accession-type ambiguity (Rfam accession vs PDB ID) and on response shape or limits, so it is only just sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the single parameter is fully documented in the schema and the baseline is 3. The description only restates that the accession identifies an Rfam family; it notably does not echo the schema's claim that a PDB ID is also accepted, leaving a small inconsistency between schema and description for the agent to resolve.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: it returns PDB entries and RNA chains mapped to an Rfam accession, plus the matched regions. That distinguishes it from most siblings, but it gives no signal for telling it apart from the closely named sibling ebi-pdbe-maps_maps_acc, whose name suggests an overlapping mapping capability.

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

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

There is no explicit guidance on when to choose this tool over ebi-pdbe-maps_maps_acc or the many ebi-pdbe entity-specific tools. The agent must infer from the word 'Rfam' that this is the RNA-family mapping path, and nothing states prerequisites, exclusions or typical workflows.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: raw q handling, the text copy field, fq object conversion, pagination controls, and expected output structure. It still omits important operational details such as default row limits or maximum result caps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and important Solr-specific notes, and the example input is helpful. However, the parameter list is lengthy and the output-format paragraph contains vague filler rather than precise return-value guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 23-parameter search tool with no output schema, the description provides a workable example and describes the output shape. It remains incomplete because it omits several grouping parameters and does not point agents to field discovery via ebi-pdbe-search_schema or document default pagination limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 23 parameters and 0% schema description coverage, the description must carry parameter meaning. It documents most parameters, including aliases and fq object conversion, but omits group_main, group_query, group_format, and group_ngroups, and several explanations are shallow or tautological.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it executes a search query against the PDBe Solr search service and exposes Solr query parameters. The purpose is clear, but it does not distinguish this generic search tool from the many specific PDBe sibling tools.

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

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

The description explains how to write Solr queries but gives no guidance on when to use this tool versus the numerous specific PDBe endpoint tools or the sibling ebi-pdbe-search_schema tool. There are no exclusions, alternatives, or routing hints.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by describing the returned schema's contents and table layout, which an agent needs in order to interpret the response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence and the follow-up routing is stated early. However, the second paragraph repeats the first, and the output-format bullets are followed by two sentences of filler ('easy to read and understand', 'allowing users to quickly grasp'), which dilute the useful content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description carries the burden of describing return values, and it does so with an explicit column listing (Field Name, Type, Stored, Indexed, Description). It omits practical notes such as output size or whether the schema is cached, but nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the baseline this scores 4. There is nothing parameter-related the description could usefully add, and it does not mislead about inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: retrieving the Solr search schema for the PDBe search service. It distinguishes itself clearly from the query-execution path by framing itself as the prerequisite step for constructing effective queries.

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

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

It says explicitly when to use it (to understand available fields) and names the follow-up action, running the query via `run_pdbe_search_query`. However, that named tool does not appear in the provided sibling list (only `ebi-pdbe-search` does), so the alternative is not verifiable for the agent, and no when-not-to-use condition is given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful content context (external-tool predictions with scores, labels, and source metadata) but says nothing about response size, per-residue volume, or why idempotentHint is false for a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that packs the resource, scope, and payload without filler. It is dense but every clause carries information; only the parenthetical examples are slightly expendable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return values, and it does so adequately by naming helices, strands, and per-residue predictions with scores and source metadata. Missing only volume/format expectations for what could be a large per-residue payload.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters, so the schema already documents pdb_id and entity_id. The description only restates 'specified PDB Entity ID' and adds no format, pattern, or cross-parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 ('Returns secondary-structure annotations for a specified PDB Entity ID') and enumerates the payload (helices, strands, per-residue predictions). That is enough to separate it from sibling annotation tools such as annot_ent or doms_ent, though it never names a sibling explicitly.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives among the many entity-scoped siblings (annot, doms, chains, var, bind_sites). The only usage signal is the implicit 'requires a PDB Entity ID', which the schema already states.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral content beyond that by disclosing the shape of the result (residue-level scores plus probability distributions), but it says nothing about response size, pagination, or what happens when an entity has no conservation data — notable given idempotentHint=false on an otherwise read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, stating the resource first and the returned contents second. It is slightly redundant with the tool's own annotation title, which repeats the same text verbatim, but the sentence itself earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only lookup with full schema coverage and no output schema, the description covers what is returned and at what granularity. What remains missing is whether results are per-chain, whether an empty result is possible, and the response encoding, which an agent would have to discover by calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema, including the 4-character PDB code constraint and the numeric entity ID pattern. The description merely restates that both are required; it adds no format or validation detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Returns') and a specific resource ('residue-level sequence conservation data') scoped to a PDB entry and entity, and it lists the payload contents (per-residue conservation scores, amino-acid probability distributions). It does not distinguish this from the many sibling per-entity tools (sec_struct, var, doms, bind_sites), all of which also take a PDB ID plus entity ID, so an agent cannot rule out alternatives from the text alone.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. The only signal is implicit in the parameter names — that this applies to one entity of one entry — which an agent must infer.

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

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

Annotations already declare this a read-only, non-destructive (though non-idempotent) retrieval, so safety is covered. The description adds genuine value by enumerating what the payload contains: residue-level scores, per-residue amino acid probability profiles, sequence identifiers, sequence length, and track colors. It says nothing about error behavior for unknown accessions or payload size, keeping it at adequate rather than rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste, with the purpose front-loaded and the payload contents listed after. Every clause carries information the agent would not otherwise have.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only fetch with no output schema, the description gives a solid inventory of the return payload, which is the main thing an agent needs. Minor gaps remain around failure modes and whether the response is large or paginated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage, so the schema already documents it. The description only repeats that the accession is a UniProt accession and adds no format or validation detail beyond that, which is the baseline case for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Retrieve PDBe-KB sequence conservation data for a UniProt accession.' Given the opaque machine-generated tool name, this does the heavy lifting of telling the agent exactly what data comes back. It does not explicitly name or distinguish itself from sibling tools such as the per-entity sequence tools, so it falls short of a 5.

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

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

Usage is only implied: the agent must infer 'use this when you need residue-level conservation data for a UniProt accession.' There is no when-not-to-use guidance and no mention of alternatives among the many sibling PDBe-KB endpoints, which is a real gap given the large sibling set.

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

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

Annotations already declare read-only, non-destructive behavior, so the description's marginal value lies in the similarity semantics it adds: the 60% PARITY threshold and the inclusion of stereoisomers and common-scaffold matches. It does not disclose result size, ordering, or whether results are bounded, which are the traits an agent would still need.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is one front-loaded sentence with no filler, and the similarity criteria are stated inline. It could have used a second short clause to cover result handling, but nothing present is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should say more about what the returned component records look like and whether the result set is bounded. It conveys the conceptual result categories well but leaves the agent without enough to predict the response shape or usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the single hetcode parameter is fully documented by the schema. The description does not add format details (e.g., case sensitivity, three-letter code conventions) beyond what the schema supplies, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Returns chemical components that are similar to the given chemical component') and defines what counts as similar (stereoisomers, shared scaffold, ≥60% PARITY similarity). It does not name or contrast with neighbouring tools such as comp_in or ligand_sum, so it is clear but not sibling-differentiated.

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

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

There is no when-to-use guidance, no statement of preconditions, and no reference to alternative tools for related component queries. The agent must infer usage entirely from the name and the similarity criteria.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds useful return-content context (ECO evidence codes, release date, source URLs, raw/confidence scores and classification labels), but says nothing about behavior such as missing annotations, error cases, or whether results are paginated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One tight, front-loaded paragraph with no filler sentences. It is somewhat dense with 'e.g:' examples (ECO_0000053, 01/06/2017, https://prankweb.cz) that are illustrative but add bulk without decision value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly explains what is returned, which is what an agent needs here. It is still incomplete for a two-parameter mandatory-filter tool: no indication of valid resource values, result size, or behavior when an entry has no annotations for that resource.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% — both pdb_id ('4-character PDB id code') and resource ('Origin/resource of the annotation') are documented in the schema, so the baseline is 3. The description does not add anything beyond the schema, notably no example or list of valid FunPDBe resource names (0 enums), which is the one gap that would have mattered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns all FunPDBe functional annotations ... for a given PDB entry ID for a specific FunPDBe annotation resource.' The scope (PDB-entry level, single resource) is clear, though it never names a sibling such as ebi-pdbe-funpdbe_for_ent_funpdbe_id to distinguish the entry-level call from the entity-level one.

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

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

There is no when-to-use guidance, no exclusions, and no pointer to alternatives. The phrase 'for a specific FunPDBe annotation resource' hints that a resource filter is mandatory, but an agent gets no help deciding between this tool and the many other annotation siblings.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's added value is the edge-case behavior it discloses: a contributing percentile of 0 forces the harmonic mean to 0, and all-unavailable percentiles yield null. The experiment_data_available flag is also explained. That is genuine behavioral context beyond the annotations, though it says nothing about permissions or response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The bulleted metric breakdown is scannable, but the lead sentence defines what the scores are rather than what the tool does, so the most decision-relevant information is not front-loaded. The content is dense rather than padded, but it duplicates the annotation title verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully documents the returned fields and their null/zero behavior, which is the right thing to spend words on. It is still incomplete as a tool definition because it never states the operation or when to select it among siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is a single required pdb_id already documented as a 4-character PDB id code. The description adds no parameter meaning at all, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explains the semantics of three named output fields (geometry_quality, data_quality, overall_quality) but never states the action itself — that this tool retrieves quality scores for a given PDB entry. An agent can infer the resource (per-structure quality metrics) but not the verb, and nothing distinguishes it from the many other per-PDB-ID sibling tools such as key_val_stats or outliers.

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

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

There is no when-to-use guidance, no mention of when a different sibling tool is preferable, and no statement of prerequisites. With ~50 sibling tools keyed on the same identifier, the absence of any routing signal is a real gap.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds that omitting assembly_id falls back to the PDBe-preferred assembly, but it says nothing about return shape, whether tunnels can be empty for an entry, or why idempotentHint is false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core purpose front-loaded and the optional-parameter default immediately after. Nothing is redundant with the title or restates the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool with no output schema and full schema coverage, the description covers purpose and the one non-obvious parameter behavior. A brief note on what a tunnel annotation contains, or the empty-result case, would make it fully self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are documented structurally, and the description goes beyond the schema by explaining the fallback semantics of the optional assembly_id (PDBe-preferred assembly). That is genuine added meaning, though the format of pdb_id is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Returns MOLE tunnel annotations for a PDB entry" gives a specific verb (returns) and a specific resource (MOLE tunnel annotations) scoped to a PDB entry. It is clearly distinct from sibling tools such as bind_sites or ligand interactions, though the distinction is inferred from the subject matter rather than stated.

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

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

The description implies use when tunnel/pocket annotations for a structure are wanted and states the default-assembly behavior, but it never explicitly says when to use this versus related PDBe annotation endpoints or what prerequisites (e.g. a MOLE-annotated entry) apply.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, so safety is covered. The description adds meaningful behavioral detail about the response: sequence and length, residue ranges in UniProt and PDB numbering, associated PDB entries, scores, confidence levels, resource links, and processed protein start positions. It stops short of discussing rate limits, pagination, or authentication, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose and then explains the return content in a structured way. It is reasonably sized for a no-output-schema tool, though the final phrase about a unified view is somewhat promotional. Overall it is clear and mostly earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the inputs and return shape in enough detail for a read-only retrieval tool without an output schema. However, it does not list valid annotation categories despite annotation_category having no enum, leaving a meaningful gap for correct invocation. It is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented structurally. The description restates that the call takes a UniProt accession and supports optional filtering by annotation category, but adds little syntax or meaning beyond the schema. With the schema doing the heavy lifting, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it provides PDBe-KB annotations for a given UniProt accession, with optional category filtering. It clearly describes the returned annotation records and metadata. It does not explicitly distinguish this tool from sibling UniProt-focused tools such as unip_var or unip_gen_unipdb, so it falls short of a 5.

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

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

The description implies usage by naming the required UniProt accession and optional annotation-category filtering. However, it gives no explicit when-to-use guidance, no exclusions, and no alternatives among the many sibling tools. The usage context is therefore only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value by enumerating what the response contains (residue coverage, observed regions, mutations, resolution, ranking scores), but says nothing about pagination, error behavior for unknown accessions, or result volume for promiscuous accessions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is correctly front-loaded in the first sentence, but the second sentence is a long undifferentiated run-on list of return attributes and the third restates the same idea. The content is useful but not structured for scanning, and the trailing sentence is largely redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only one input parameter, the description has to describe the payload, and it does so in unusually rich detail. Only the absence of guidance on result shape variability and sibling disambiguation keeps it below a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter with 100% schema description coverage, so the schema already carries the documentation burden and the baseline of 3 applies. The description adds no meaning about the accession itself, e.g. whether UniProt IDs are accepted alongside accessions or how isoforms are handled.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource: retrieve PDB structures mapped to a UniProt accession. That is far clearer than the opaque tool name, but it never distinguishes this tool from close siblings such as unip_gen_annot, unip_map_ent, or unip_giruiru/ipuipu, which operate on the same UniProt accession axis.

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

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

Usage is only implied by the closing line about providing an 'integrated view' of how PDB structures align with a UniProt sequence. There is no explicit statement of when to pick this over the many other unip_* siblings, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description is not required to repeat it. The description adds some behavioral context by sketching the response (amino-acid sequence for polymeric entities, total sequence length, residue array with processed-sequence start positions), but does not say whether results can be empty for non-interface proteins or how large the payload may be.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, which is good, but the following sentences pad rather than inform: 'The response provides the type of data included' is vague filler, and the closing sentence about 'enabling analysis' restates the use case without adding constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single required parameter and no output schema, the description partially carries the return-value burden by naming sequence, total length and residue-level items. That sketch is imprecise and omits error/empty-result behavior, so it is adequate but not complete for a tool whose only structured documentation is one field.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is documented in the schema, so the baseline is 3. The description adds no meaning beyond that — no accession format example, no statement about which namespaces or entry types are accepted, and no indication of what happens with an invalid accession.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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: 'Retrieve detailed information on interface residues for a given UniProt accession', which is far more than a restatement of the name. It does not, however, distinguish this tool from the entity-based interface-residue siblings (ebi-pdbe-iface_res_ent_interfaces_id_entity_id, ebi-pdbe-ent_iface_res_ent_iface_res_id), so an agent cannot tell which addressing scheme to pick.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of the entity-ID alternatives in the sibling list, and no stated prerequisites. The agent must infer from the parameter alone that this is the accession-based route into interface residues.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful context about the payload shape (partner names, antibody-role annotations, PDB structures, self-directed flag), which tells the agent what kind of data comes back. It does not address the unusual idempotentHint=false for a pure retrieval, nor pagination, response size, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the verb and resource, with the output enumeration immediately following. The trailing sentence ('This endpoint provides structural and functional context...') is largely filler that restates the value proposition rather than adding operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with no output schema, the description is close to sufficient: it explains both the input concept and the fields returned, which is the main thing an agent cannot infer without an output schema. Missing are sibling disambiguation and any note on result volume or limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter exists and schema coverage is 100%, so the schema already fully documents 'uniprot_accession'. The description adds no format guidance (e.g., accepted accession patterns, isoform handling) beyond restating that the input is a UniProt accession, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Retrieve') and a precise resource ('interaction partners for a given UniProt accession'), and it enumerates what the result contains (partner names, antibody-role annotations, observed PDB structures, self-interaction flag). It does not, however, contrast itself with sibling tools such as ebi-pdbe-unip_giruiru_acc or ebi-pdbe-comp_intx_proteins, which also take UniProt accessions and deal with interactions, so the agent gets no help disambiguating.

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

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

There is no explicit when-to-use or when-not-to-use guidance, no mention of alternatives among the many unip_* and comp_intx_* siblings, and no stated prerequisites. The only implicit signal is that this is the partner-lookup endpoint for a UniProt accession.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds genuine value by disclosing the shape of the result (accessions, alignment ranges, Best Chain ID), which matters because there is no output schema, but it does not address the oddly declared idempotentHint=false on what appears to be a pure lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, and the resource being returned is named first. It is dense but every clause carries information about the returned content rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does its main duty by summarizing the return fields, which is a real contribution. It still leaves gaps for a two-parameter lookup: no indication of what happens with an unmapped entity, whether multiple mappings can be returned, or how the Best Chain ID relates to other chain-scoped tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both required parameters (pdb_id, entity_id with its numeric pattern) are documented in the schema. The description only reinforces that entity_id is the scoping key for the mapping; it adds no format, validity, or edge-case detail beyond the structured fields, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Returns UniProt mappings for a specific PDB Entity ID', and enumerates the payload (accessions, residue-level alignment ranges, Best Chain ID metadata). It does not distinguish itself from lookalike siblings such as unip_giruiru, unip_ipuipu, or maps, so an agent must infer the split from names alone.

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

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

There is no guidance on when to choose this tool over the many other entity-scoped endpoints (sec_struct, doms, chains, var, annot) or over the other UniProt-oriented tools. No prerequisites or exclusions are stated; the usage context is only implied by the phrase 'PDB Entity ID'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description does not contradict it. The description does add useful behavioral context about what comes back (sequences, variant features, PolyPhen/SIFT predictions, cross-references), which matters because there is no output schema. It says nothing about pagination, rate limits, error behavior for unknown accessions, or why idempotentHint is false on a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by return-value detail, which is the right ordering for a fetch tool. The closing phrase 'enabling comprehensive analysis of protein sequence variations' is pure filler and the return enumeration is long, but overall the text stays on topic.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the return-value burden and it does so thoroughly, listing sequence, identifiers, variant features, clinical significance, and predictions. The remaining gap is operational guidance (routing vs siblings, behavior for invalid accessions) rather than missing output information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single required parameter, so the schema already explains the input and the description adds little beyond it. It implies the accession must be a UniProt (not PDB) identifier, which is mildly useful disambiguation, but adds no format or validation detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Retrieve variation details for a given UniProt accession.' That is unambiguous about what is fetched and the keying identifier. It does not, however, distinguish itself from structure-side siblings such as ebi-pdbe-var_ent_var_id_entity_id, which is also variation-related but keyed by PDB entity, so an agent must infer the difference from the parameter name alone.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. The description never says to prefer this tool over the PDB-entity variation sibling or over the other UniProt-keyed tools like unip_giruiru or unip_gen_annot, leaving routing entirely to inference from the accession parameter.

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

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

The annotations declare readOnlyHint=true, but the description explicitly states the tool supports 'adding/removing scenes and structures, component or annotation layers, and changing layer visibility,' which are mutating operations. This is a direct contradiction. Additionally, destructiveHint=false conflicts with removing scenes/structures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then provides operational details in a logical order. It is somewhat long but each sentence adds relevant context about host routing, ID matching, and validation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (huge schema, no output schema, mutation behavior), the description covers many important operational traits: no global server state, host routing to existing Apps, validation when no operations are provided, and that the App does not calculate scientific measurements. It still omits the compact_response behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains expected_revision as concurrency control and calls operations 'atomic,' and it notes the workspace should be the latest complete version. However, it does not mention the compact_response parameter at all, and with only 25% schema description coverage, the description does not fully compensate for the gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Compose or restore a molecular workspace in the shared viewer.' It is clear what the tool does, though it does not explicitly differentiate itself from the many sibling PDB data tools.

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

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

It gives clear context for when to use it: 'Supply the latest complete workspace from tool results or App context, expected_revision, and atomic operations' and 'No operations validates and restores a saved workspace.' It also explains host routing behavior. However, it lacks an explicit when-not-to-use statement or named alternative.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's job is to add substance, which it does: it discloses the residue-position remapping behavior and enumerates the returned feature content (variant type, alternative sequence, position, evidence, cross-references, clinical/functional annotations, structural-impact metadata). It does not address the odd idempotentHint=false on what appears to be a pure read, nor whether entities lacking a UniProt mapping return an empty result or an error.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the verb and resource, with the return-content enumeration placed second. The long list of feature fields is dense but each item conveys real payload information; no filler or repetition of the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and only two fully documented parameters, so the description bears the burden of describing the response, which it does thoroughly — mapped accessions, variant features, evidence, cross-references, and structural-impact metadata. Combined with readOnlyHint annotations, an agent has enough to call this correctly and anticipate the shape of the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented in the schema, so baseline 3 applies. The description adds modest meaning by explaining that entity_id is the molecule whose residue numbering the results are remapped to, but it does not clarify pdb_id formatting or what happens with entity IDs that have no UniProt cross-reference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Returns UniProt sequence-variation annotations for a specified PDB Entity ID', with the additional qualifier that positions are remapped to the entity's residue positions. This distinguishes it in substance from the accession-keyed sibling ebi-pdbe-unip_var_unip_var_unip_acc_6a476541, but the description never names that alternative, so the differentiation must be inferred.

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

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

Usage is only implied: an agent can infer it should call this when it holds a pdb_id plus entity_id and wants variant data for that entity. There is no explicit statement of when to prefer this over the UniProt-accession variant tool or the unip_map tool, and no prerequisites (e.g. entity must map to a UniProt entry) are mentioned.

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