plan_download

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

With no annotations, the description carries the full burden and does so well: it discloses that no metadata or images are requested by default, that init plugins still run per their own behavior, that include_details=True performs network reads with per-item failure isolation, that no size/time estimation is done, and that a missing img2pdf yields an actionable error without auto-install. Remaining gaps (auth needs, rate limits, write/side-effect profile) keep it from a 5.

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?

Front-loads the core purpose in the first line, then groups parameter behavior and edge-case disclosures. The description is long and clause-dense, but for a 7-parameter tool with zero schema coverage and no annotations, nearly every sentence carries useful information.

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?

Given an output schema exists, return values needn't be explained, and the description instead covers behavior, parameter meaning, concurrency defaults, and error handling for a fairly complex tool. It is nearly complete; the main omission is any explicit positioning against the actual download siblings it previews for.

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 compensate, and it largely does: it explains kind (album/photo), export_formats (zip/pdf/long_img), album_workers (albums only, default 3), photo_workers/image_workers (batch chapter/image caps inheriting download.threading defaults), and include_details semantics. Only the required 'ids' parameter's concrete format/kind coupling is left implicit, but it is covered by the ID-normalization clause.

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?

States a specific verb + resource in '下载前预览' and enumerates exactly what it does (normalize/dedupe IDs, resolve output root, set global concurrency caps) and what it does NOT do ('不下载图片'). This clearly separates it from sibling download/start tools like download_batch, download_album, and start_download.

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 'before download' framing implies when to use it, and include_details=True is positioned as the path for selecting a subset of chapters. However, it never explicitly names an alternative tool or states when NOT to call this versus download_batch/start_download, so the guidance remains implied rather than explicit.

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