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

Annotations already mark this as destructive and non-idempotent, but the description adds substantial behavior beyond them: operations run sequentially feeding each other, a Transcribe stage is auto-inserted, invalid configs are refused with valid options listed, rendering happens in the background, credits are spent, and the required scopes are stated. No contradiction with 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 every sentence earns its place. It front-loads the core purpose and examples, then moves through alternatives, execution semantics, validation, sourcing, async behavior, and scopes in a logical order. No filler or repetition of schema fields.

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 complex, destructive, async, credit-spending tool with no output schema, the description is remarkably complete. It covers what the tool does, how to invoke it correctly, prerequisite knowledge, validation behavior, source restrictions, background rendering, polling, and required scopes. Nothing needed for correct invocation is missing.

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?

Although schema coverage is 100%, the description adds meaning the schema does not: sourceUrl must come from list_assets or a run's outputs, operations execute in order with outputs chained, the asset is automatically wired as an input, and nodeType must exactly match list_node_types. The input examples for extra named ports clarify the intended JSON shape.

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 opens with a specific verb and resource: 'Run pipeline nodes over ONE video, image, or audio file the account already has and get the edited file back.' It enumerates concrete transform examples and explicitly contrasts with assemble_video, so an agent can distinguish it from the closest sibling without inspecting schemas.

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 when-to-use context ('Run pipeline nodes over ONE...'), names an alternative condition ('To put music under a video, use assemble_video with musicPrompt instead'), and provides prerequisites: check get_node_type first and source assets from list_assets or get_run outputs. This is strong routing guidance.

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