ebi-pdbe-build_mvs

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.