video_download

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

With no annotations, the description carries the full burden of disclosing behavior. It states the operation (download via yt-dlp), the output (file path), and the default output location. However, it does not disclose potential side effects such as network latency, disk usage, or error conditions (e.g., invalid URL). It also does not mention if the file is overwritten. This is adequate but not thorough, so a 3 is appropriate.

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 well-structured: a clear first sentence stating the core function, followed by supporting details and a bulleted list of arguments. It is not excessively verbose, though the Args block could be more compact. The main purpose is front-loaded, making it easy for an agent to quickly grasp the tool's role. Slightly high length, but efficient overall.

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 download tool with four parameters and an output schema (which presumably indicates the return value), the description covers the purpose, parameter semantics, defaults, and return value. It does not mention error handling or prerequisites (like network access), but these are inherently implied. The description is complete enough for an agent to call the tool correctly without additional information.

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?

The schema has 0% description coverage, so the description must compensate. It does so by explaining each parameter: source (URL), resolution with specific options ('480p', '720p', '1080p', 'best'), audio_only (meaning and format m4a/opus), and output_path (target path with default). This adds significant semantic meaning beyond the schema's types and defaults. It could mention that resolution is ignored if audio_only is true, but it's not critical; a 4 is justified.

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 action: 'Download a video (or just its audio) from a URL to disk via yt-dlp.' It identifies the target resource (video/audio from URL) and the mechanism (yt-dlp), and mentions the return value. This distinguishes it from siblings like video_extract_audio (which works on local files) and video_info (which inspects) — the verb 'download' is specific and unambiguous.

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?

The description provides context that this tool is for downloading from URLs ('Supports YouTube and 1000+ other sites'), which implies web sources. It does not explicitly name alternatives or state when not to use it, but the context is clear enough. The absence of exclusion is a minor gap; a 4 is warranted because the purpose is clear and the agent can infer when to use it.

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