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

Annotations only declare the write/non-destructive profile, while the description adds the details an agent actually needs: the operation is free, takes minutes and is asynchronous (poll get_status), can pause at a human review gate with a link, and is resumed by invoking the same tool again. It also discloses the refusal/continue path around keep_length. These are behavioral traits well beyond what annotations convey.

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 core action and its free/no-render nature are front-loaded, and each sentence carries distinct information (duration, polling, pause/resume, cancellation). The final sentence runs long and packs three ideas together, which slightly hurts scanability but not comprehension.

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 an asynchronous, multi-stage build tool with no output schema, the description covers cost, duration, polling, review-pause semantics, resumption, and early cancellation — enough to invoke it correctly. It is silent on what a completed plan looks like or what apply_plan does next, which would have closed the lifecycle.

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 67%, and the schema already documents both decision and keep_length, so the baseline is 3. The description adds context for resuming after a review pause and for continuing past a refusal, but it never mentions the decision enum (keep_cut vs retry) or project_id, so it does not meaningfully extend parameter meaning beyond the schema.

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 resource ('Turn the stored script into the full production plan') and enumerates the artifacts produced (scenes, characters, locations, shots, continuity review). It also pins down scope by saying this is the same run the Script page starts and that no renders are fired. It does not differentiate itself from nearby siblings like apply_plan or regenerate, which is the only reason it falls short of a 5.

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 concrete operational guidance: poll get_status while it runs, call build_plan again after a human approves a review pause, and use run_control(action: "cancel_build") if the script needs changing first. That names a real alternative and its trigger condition. It never states when not to use this tool versus apply_plan or regenerate, so it stops at 4.

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