capture_before_after_reference

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

No annotations are provided, so the description must fully disclose behavior. It says 'preserve two genuine exported frames' but does not explain what 'preserve' entails (e.g., creates a still, overwrites existing files, any side effects on the timeline). It also fails to mention if the operation is destructive or safe. The agent lacks critical information to predict tool 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 description is one short sentence, which is concise but not optimally structured. It front-loads the core action ('preserve two genuine exported frames') but omits critical details. While no words are wasted, the brevity sacrifices completeness, making it merely average in usefulness.

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 5 parameters (2 required) and an output schema, the description is insufficient. It does not explain parameter roles, return value (e.g., success indicator, paths of saved frames), or any post-conditions. The output schema exists but the description fails to leverage it or provide necessary context for effective use.

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 input schema has 5 parameters, but none have descriptions (schema description coverage 0%). The tool description only mentions 'two genuine exported frames' (relates to before_reference and after_reference) and 'optionally combine them side by side' (relates to create_side_by_side). It does not explain overwrite, output_name, or the exact format/meaning of the reference parameters. The agent gets almost no additional meaning beyond parameter names.

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 the verb 'preserve' and specifies 'two genuine exported frames' and 'optionally combine them side by side', which clearly indicates the tool captures a before/after pair and can create a composite. It distinguishes from sibling tools like capture_current_frame (single frame) or list_captured_references (view only). The term 'preserve' is slightly less direct than 'capture', but the purpose is clear.

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 provides no guidance on when to use this tool versus alternatives like capture_current_frame or capture_clip_reference. There is no mention of prerequisites, context (e.g., current timeline selection), or when to avoid using it. The agent is left to infer based solely on the name and short description.

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