add_overlay_to_video

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

Annotations only cover the safety profile (not read-only, open-world, not destructive). The description adds real behavioral context beyond them: async execution via job_id with job_status polling, output codec/container and resolution cap, the automatic aspect reauthorization, and the privacy guarantee that local media never uploads.

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?

Information is front-loaded: purpose, then constraints, then return contract, then the sibling routing rule last. Dense and mostly waste-free, though the aspect/output-format sentences are tightly packed and slightly harder to parse than they need to be.

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?

With no output schema, the description correctly carries the return contract (job_id + job_status polling) and the output characteristics. The one gap is output_path semantics, which is neither in the schema description nor the tool description.

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% (only configuration is documented). The description adds meaning for start_seconds ('must fit the overlay within the video') and clarifies the aspect return, but video_path and output_path receive no explanation despite being required/undocumented.

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 gives a specific verb+resource ('Render an overlay ... composite it onto one local video') plus scope constraints (up to 60 seconds, positioned at start_seconds). It is clearly distinguishable from siblings like render_overlay and edit_video without opening any 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 explicitly routes the agent: 'Use edit_video for longer or multi-clip edits', and states the precondition that the start must fit the overlay within the video. The when-to-use and when-to-use-something-else conditions are both present.

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