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

Annotations already cover readOnly, idempotent, non-destructive, closed-world, so the bar is lower; the description still adds real context beyond them: no purchase occurs, original identity is preserved, and results are never stitched from agent-local clips. The instruction to persist all returned IDs in host/widget state is useful operational behavior. It stops short of describing what the response contains or what happens when a project has no finished render.

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 cost disclaimer is correctly front-loaded, followed by what is recovered, then the state-persistence instruction and the authority note. Every sentence carries a distinct claim, though the identity/no-joining pair is close enough in meaning to feel slightly repetitive.

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?

There is no output schema, so the description must carry the return contract, and it only partially does (persist returned IDs, one render per result). It omits the meaning of the variant input fields, the relationship to soclo_video_variants_quote/approve, and any guidance on partial or missing results, which leaves the recovery workflow underspecified.

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?

With one top-level parameter at 100% schema description coverage, the baseline is 3. The description adds nothing about the `variants` array itself: the nested item fields (label, hook, projectId, revision, clientRequestId, quoteId, makeReady, expectedCredits) have no descriptions anywhere, and the text never explains why they are supplied or what 'revision' and 'clientRequestId' are for.

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 states a specific action and resource: recover each canonical finished film from its saved project/generation, keeping original identity. It also disambiguates the result unit (one result = one finished Soclo render, not joined agent-local clips). However, it never distinguishes this from the very similarly named siblings soclo_video_recover, soclo_video_status, and soclo_video_variants_approve, and the name says 'status' while the text describes recovery.

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?

'Free; never purchases' implies this is the no-cost path when a render already exists, and 'Wallet/ledger and soclo_video_make remain authoritative' implies make is the paid alternative. But there is no explicit statement of when to choose this over soclo_video_recover or soclo_video_status, and no stated precondition (e.g., a prior variants quote or approved variant). Usage is only implied.

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