dubbing_export_youtube_package

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

Annotations already declare non-read-only, idempotent, non-destructive and closed-world, so the description's job is to add context beyond that — and it does, by disclosing that the tool writes a concrete file tree and that the YouTube API cannot upload audio, so the user completes publication manually. It does not say where the folder is written, whether an existing package is overwritten, or what happens if no dub track exists yet.

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?

Two sentences, front-loaded with the action and artifact list, and the closing sentence about manual upload earns its place by preventing a wrong assumption about API uploading. The inline file enumeration is long but each item is informative, so there is little waste.

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?

An output schema exists, so return values need not be described, but for a file-writing tool with 0% parameter coverage the description omits the destination path, overwrite/idempotency behavior in user terms, and the render prerequisite. It is adequate to recognize the tool but not complete enough to call it confidently in edge cases.

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 0%, so the description must carry parameter meaning, and it only partially does: 'one folder per language' hints that 'languages' scopes output, but never states its format, nor whether null/omitted means all languages. 'project_id' is never referenced at all, leaving a required parameter entirely unexplained.

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+resource ('Write the YouTube upload package') and then enumerates the exact artifacts produced (audio.m4a, captions.srt, title.txt, description.txt, UPLOAD-TO-YOUTUBE.md), which makes it clearly distinguishable from siblings like dubbing_render or dubbing_project_status. It stops short of explicitly naming the sibling it follows, so differentiation is inferred from the artifact list rather than stated.

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?

Usage is only implied: the wording ('the dub track, video length') suggests it is the downstream packaging step after a render, but no prerequisite (e.g., 'run dubbing_render first') and no alternatives or when-not conditions are given. The note that the user must upload manually clarifies what happens after, not when to call this tool.

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