generate_shot_frame

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

With no annotations, the description carries the full behavioral burden, and it delivers: it discloses that regeneration overwrites existing frame images, marks the shot video as pending regeneration, preserves the unaffected side when reopen_pair_id is used, does not re-bill for preserved candidates, and explains completion via polling get_storyboards. It also warns against unauthorised confirmation, making side effects and process risks clear.

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 dense but well-organized: the core action and side effects come first, followed by the reopen_pair_id inheritance flow, then the mandatory quote confirmation warning. Every sentence carries operational meaning; the length is justified by the tool's complexity and the need to prevent incorrect retry or billing behavior.

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 no output schema and a complex asynchronous workflow, the description is remarkably complete. It covers prerequisites, side effects, overwrite behavior, billing implications, the exact polling completion condition, and the required quote confirmation ritual. An agent has enough context to call the tool correctly in both the normal and reopen_paths.

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 83%, so the baseline is already decent. The description adds real semantic value beyond the schema by explaining how reopen_pair_id interacts with frame_type, how quote_id must be obtained and matched, and the default behavior for image_model. The only notable gap is storyboard_id, which has no schema description and is not explicitly explained in the description, though its meaning is inferable from the tool's context.

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: generating or regenerating a frame for a single shot, and says it is asynchronous. It distinguishes itself from the external 'generate + upload' path, explicitly positioning this tool as the correct way to fix a shot's frame, which differentiates it from sibling upload tools like upload_shot_frame.

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 gives explicit when-to-use guidance: use this instead of external tools because they break consistency; use reopen_pair_id only when get_storyboards returns that field, otherwise use normal frame_type retry. It also gives a concrete prerequisite for tail frames and mandates the quote-before-call flow, so an agent knows exactly when and how to invoke it.

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