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

Annotations only say non-readonly, non-idempotent, non-destructive; the description goes far beyond by disclosing that redo is paid, that reference_redo_confirmation returns a price which must be shown and accepted before resending with confirmed and max_credits, that failed-status redo is free, and that stop refunds everything except images already made. These are exactly the cost and irreversibility facts an agent needs before mutating a shoot, and the 'destructiveHint: false' annotation is implicitly clarified by the refund caveat.

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?

Everything is packed into one long run-on paragraph with statuses, actions, pricing and refunds interleaved, which makes it hard to scan; front-loading the purpose is good, and little text is pure filler. The appended Arguments JSON blob duplicates the schema and could be dropped, and per-status last-presentation order would be cleaner.

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 two-parameter but stateful and nested tool with no output schema, it covers the lifecycle, all four actions, the paid-redo handshake, free failed-status redo, and the refund boundary of stop. Gaps are the shape of the returned references (items[].group is referenced but never described) and the reference_redo_confirmation payload, which an agent must parse to quote a price.

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 reported at 0% for the top-level params, so the description must carry weight, and it does: it explains the action lifecycle, that groups are image numbers, that defect=true means a genuinely wrong image (face, hands, product) versus a requested change, and the confirmed/max_credits price handshake. It never explains the path params (id, shoot_id) or what references.items[].group indexes into, and the trailing literal Arguments JSON snippet is redundant against 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?

The description identifies a specific resource (reference images, one per camera and place of the person) and pins it to a lifecycle position: after kelpo_accept_shoot and before any shot is rendered. It is not phrased as a clean verb+resource, opening with a noun phrase and immediately diving into state machinery, but an agent can still tell exactly what it operates on and where it sits relative to 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?

It gives explicit branch conditions keyed to kelpo_get_shoot's references.status: when awaiting, use show then wait for the person, then validate or redo; when failed, redo those groups for free; stop cancels the video. It also names the exact sibling to check first and the follow-up calls, so no routing is left to inference.

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