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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description goes beyond them by stating that accepted clips are preserved, that the recovery batch ID is returned, and that credits may be spent. The credit-cost disclosure and the preserved-work guarantee are exactly the kind of context annotations cannot express, though side effects on the original batch remain unspecified.

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?

Three sentences, no filler, with the core action front-loaded and the operational caveats (credit spend, retry key) trailing in priority order. Dense without being cryptic, though the middle sentence could be folded into the first.

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?

An output schema exists so return values need not be explained, and the destructive/idempotent annotations cover the safety burden. Gaps remain on the input side: half the parameters are undocumented in both schema and description, and there is no statement of what happens when targetClipCount is null or how partial failures are surfaced.

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 only 25% (batchId's 'UUID string.'), so the description must carry more weight than it does. It usefully ties the idempotencyKey to retry safety and gestures at targetClipCount via 'missing clip count', but says nothing about workspaceId, the 1-30 bounds, or the null defaults on workspaceId/targetClipCount.

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 (recover) and resource (a terminal batch's missing clip count) and grounds it in a named workflow, so the agent knows this is a recovery action rather than a general clip operation. It does not, however, distinguish itself from close siblings like clips_repair or clips_reselect, leaving the agent to infer which recovery path applies.

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 implies when this applies ('terminal batch', missing count) and gives retry guidance ('retry with the identical idempotency key'), which is genuinely useful. It stops short of naming alternatives such as clips_repair/clips_reselect or stating exclusions, so routing between the three recovery tools 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.