下载视频 / 音频 / 弹幕 / 字幕 / 封面

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

Beyond the annotations it discloses the concrete output location (~/Downloads/bilibili, overridable via BILIBILI_DOWNLOAD_DIR), the ffmpeg merge-and-chapter-metadata behavior, and the graceful fallback to separate files when ffmpeg is absent — none of which the annotations convey. It still leaves out whether files are overwritten on re-download, whether login/cookies are required, and any rate-limit behavior for batch pages.

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 leads with the action and destination, then layers merge behavior, extras, and the async/status flow in a logical order with no filler. It is dense but each clause (directory override, ffmpeg fallback, task ID handoff) carries actionable information; only the closing Bilibili-Evolved naming is low-value padding.

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 an 8-parameter tool with no output schema, it covers the essentials an agent needs: where files land, how merging behaves, and how the async return is used. It doesn't describe the shape of the immediate response (e.g., task ID field name, progress fields) which matters when wait_seconds is 0, leaving a small gap before the bili_download_status handoff.

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 100%, so every parameter including mode, codec, pages and wait_seconds already carries its own explanation; the description adds no parameter-level detail beyond restating the ffmpeg merge and the wait_seconds timeout behavior. That meets the baseline for a fully documented schema but doesn't improve on it.

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 first sentence states a specific verb (下载到本机) plus resource and destination, and the tool's scope is further sharpened by naming which artifacts it can fetch (视频/音频/封面/弹幕/字幕). It is clearly distinguishable from siblings like bili_danmaku or bili_subtitles because it frames them as optional extras of a single download job, and from bili_download_status because it names that tool as the follow-up.

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 says the task runs in the background, that exceeding wait_seconds returns a task ID, and that bili_download_status is the way to check afterwards — a clear usage path. What's missing is routing guidance versus the dedicated siblings (bili_danmaku, bili_subtitles, bili_chapters) when the user only wants danmaku/subtitles, and any note on prerequisites such as login for high qualities.

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