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

Annotations already mark readOnlyHint=true, and the description reinforces this with 'Free to call' and positions it as a pre-flight check before a mutating sibling (create_scene). It adds valuable context beyond the annotation by stating it runs 'the same math the editor preview runs', which signals the output is faithful to the actual render, and clarifies that it only reports 'moving' props.

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 with zero filler. The core purpose is front-loaded, the contrast with validate_scene is packed into the second sentence, and the workflow guidance is a compact one-liner. Every sentence 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?

Despite no output schema, the description tells the agent what the return shape looks like (value series per moving prop), how faithful it is (same math as editor), when to use it (motion checking before create_scene), and that it is safe to call repeatedly. Combined with the fully described parameters and read-only annotation, nothing essential is missing 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. The description adds little parameter-specific meaning beyond the schema; it references 'N evenly spaced times' which maps to samples, and 'each moving prop' hints at element_ids, but it does not define defaults, formats, or filtering behavior beyond what the schema already states.

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: 'Numerically preview a scene' and explains exactly what it evaluates (keyframes AND node graphs) and returns (a value series per moving prop). It also distinguishes itself from validate_scene, making the purpose unmistakable even among ten 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?

Usage context is explicit: it says validate_scene checks structure while this checks MOTION, and lists concrete confirmations (ranges, spring overshoot, stagger offsets, elements actually move before create_scene). It even provides workflow guidance ('Free to call — iterate: author → sample → adjust'), which tells the agent exactly when and how often to invoke it.

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