Update a YouTube video’s title, description, tags or privacy

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

Annotations already indicate mutation (readOnlyHint false) and non-destructive (destructiveHint false), but the description adds crucial behavioral context: the public visibility warning, the requirement for explicit user confirmation, the 'fields you omit are left untouched' semantics, and the prerequisite of a connected YouTube channel. These go beyond annotations and inform safe usage.

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 somewhat long but every sentence adds value: it lists the edited fields, gives the critical privacy-flip use case, warns about public visibility, states partial-update behavior, and mentions the channel prerequisite. It is front-loaded with the main purpose and avoids fluff, though it could be tightened slightly by merging the privacy warning and confirmation requirement.

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 tool with 5 parameters, one enum, and no output schema, the description covers all essential operational aspects: what it does, the key use case, safety considerations, partial update behavior, and the prerequisite. Nothing critical is missing for an agent to call it correctly.

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 covers 80% of parameters with descriptions, so baseline is 3. The description adds meaning for privacy (explains unlisted/public/private implications) and clarifies optionality with 'Fields you omit are left untouched.' However, it does not elaborate on the 'tags' parameter, which lacks a schema description, leaving some gap. Astill beneficial boost over the baseline.

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 clearly states the tool edits an existing video's title, description, tags, or privacy, distinguishing it from post_to_youtube (which creates) and delete_youtube_video. It also highlights the specific privacy-flip use case, making the tool's purpose unambiguous and distinct from siblings.

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?

Explicitly names post_to_youtube as the alternative and states when to use this tool (to flip an unlisted upload to public). It also instructs to confirm with the user before making a video public, and mentions partial updates. This gives clear when-to-use and when-not-to-use guidance.

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