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

Annotations already declare that this is a non-read-only, open-world, destructive operation, and the description adds substantial behavioral detail beyond them: it spends credit, costs about $9.3 of engine cost on a default call, bills face-only likeness at about $0.10 per presenter second, takes 10 to 60 minutes, requires the write scope, and returns a media key. It also explains budget capping, chargedUsd reporting, and that max_usd can make the processor refuse a plan before spending. This is exactly the operational context an agent needs before invoking an expensive mutation.

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-loaded: it starts with what the tool does, then modes, time, cost, and scope constraints. Every sentence carries useful information, though the cost discussion is repeated across the main description and multiple parameter notes. It is appropriately sized for a complex, expensive tool, but not maximally tight.

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?

The tool is high-complexity, high-cost, and potentially destructive, and the description covers the critical gaps: spend magnitude, budget caps, runtime, output media key, write scope, and mode-specific behavior. An output schema exists, so return values need not be explained further, and the annotations already carry the safety profile. Nothing essential 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: recording_media_key replaces the presenter and voice at no Omni cost, face_media_keys drives generated likeness, only_segment is the cheap probe, and max_usd/budgetUsd cap spend. It does not explain every parameter relationship, notably resume_from and name, but the cost and mode interactions it does explain go beyond 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 states a specific verb and resource: remake a reel at a URL with the account owner as presenter, preserving cuts, shots, timing, and captions. It also distinguishes the two operating modes (recording versus face-only likeness generation) and names measure_reel as the script source for recordings. An agent can identify exactly what this tool does without opening the schema.

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 conditions: only for a reel the user asked to copy, with their own face and voice, and recording_media_key required unless face_media_keys are provided. It also states that only_segment is the cheap probe before a full clone and that face-only generation is capped by max_usd and labelled AI-generated. Those constraints and exclusions make the correct use case unambiguous.

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