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

Annotations already declare destructive, open-world, and non-idempotent behavior. The description adds valuable operational context: 120-second / 500 MB limits, provider chunk joining, audio restoration, model-specific constraints, and that it returns a tracked task and playable result. It does not discuss idempotency or cost enforcement beyond what the schema provides, but adds substantial behavior beyond annotations.

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 description is dense but front-loads the core operation and constraints. Most sentences carry operational weight (limits, model support, special cases, return behavior). It is appropriately sized for a complex 22-parameter tool, though it could be slightly tightened.

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?

Given the high parameter count, nested objects, and existing output schema, the description covers the critical operational details: preset behavior, size/duration limits, model-specific rules, and output nature. It does not need to explain return values because an output schema exists, but it leaves some parameters (e.g., idempotencyKey, maxCostUsd) to the schema.

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 82%, so the baseline is 3. The description adds model-specific parameter meaning: LTX supports specific aspect ratios and should omit the prompt, SwitchFrame requires a workspace image in mediaInputs.reference_image_uri, and model selection should use get_model_catalog. These details help interpret several parameters beyond the schema text.

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 verb and resource ('Run the Reframe preset on a complete workspace video'), names concrete operations (outpaint, join chunks, restore audio), and provides size/duration bounds. It distinguishes the tool from generic video generation by emphasizing the Reframe preset and supported reframe models.

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 clear context for use: supported models, LTX aspect ratio behavior, SwitchFrame's mediaInputs.reference_image_uri requirement, and the instruction to call once per variant. It also routes to get_model_catalog. It lacks an explicit comparison to sibling tools like edit_video or generate_video, so usage is clear but not fully alternative-aware.

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