ebi-pdbe-build_mvs_story

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.