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

Beyond the annotations it discloses real behavior: optimistic-concurrency requirement on expected_brief_revision, the absence of side effects ('No media generation, credit charge or library change'), and the return payload ('a new brief and quote'), all useful given there is no output schema. It stops short of describing what happens on a revision mismatch or whether the previous step is lost on replace.

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?

Four compact sentences, front-loaded with the mutation mode and ending with the next-action instruction; almost nothing is filler. The telegraphic packing ('Photo format is shared across the shoot') and the dangling 'read the returned recipe_key' make it slightly cryptic rather than maximally efficient.

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 10-parameter, 6-required mutation with no output schema, the description covers the mutation model, concurrency, side-effect scope and return shape — the essentials. But several required parameters (shot_index, length_seconds, board_id) and the failure mode for a stale revision go unexplained, leaving real gaps for a planning write.

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 only 40%, so the description is carrying weight — it clarifies step_index's append-vs-replace semantics, that look_keys defaults to every look on the flow, that recipe_key is a flow from the current brief, and that expected_brief_revision is the current one. It says nothing about length_seconds, sound, prompt, shot_index bounds, or what 'Photo format is shared across the shoot' constrains.

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 opening verb phrase 'Append or replace one image-to-video step' names the operation, the object, and its two modes, which immediately separates it from plan_shoot_image and plan_shoot_edit in the sibling list. Scope is further pinned down ('Revises the selected looks using the named brief flow') so the agent knows it is a plan-level step, not a generation.

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?

It states when the edit applies (default: all looks using the flow, 'requires the current brief revision') and closes with an explicit follow-up rule: 'Read the returned recipe_key before the next edit.' What is missing is any exclusion or sibling routing — it never says to use plan_shoot_image for stills, remove_shoot_step to undo, or what to do when the revision is stale.

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