download_album

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

With no annotations provided, the description carries the full burden and does it well: it discloses blocking semantics ('会等待下载完成后返回'), real-time progress through logs and MCP Context, cache-hit behavior in image_paths, a per-call log_path, task_id, and an error field on failure. This gives an agent a concrete execution model for a long-running, side-effecting operation.

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?

Well-structured and front-loaded: a one-line summary, then behavior, then parameters, then return fields. The nine-field return listing is lengthy, but it is the only return documentation available since the output schema is not shown in the definition, so every sentence earns its place.

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 single-required-param download tool with no annotations, coverage is strong: purpose, blocking behavior, parameter format, progress reporting, return structure, and failure reporting are all documented. The notable gaps are lack of prerequisites (login is a sibling tool) and lack of explicit routing against download_photo/download_cover, which would make it fully complete.

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 coverage is 0% and the schema only names album_id as a string, so the description must compensate. It adds an example format ('123456') for album_id and, crucially, documents the ctx parameter as auto-injected by FastMCP — preventing the agent from attempting to pass a parameter that is not part of the input schema.

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 and resource — '在后台下载整个本子' (download the entire album) — which an agent can immediately distinguish from the download_photo and download_cover siblings. The '在后台' (in background) phrasing is mildly confusing because the very next sentence declares it a blocking operation, which prevents a 5.

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 phrase '整个本子' (entire album) implicitly tells an agent this is the tool for full albums rather than single photos (download_photo) or covers (download_cover), but no explicit when-to-use/when-not-to-use guidance is given and no alternative tool is named. Prerequisites such as authentication are not mentioned, even though a login sibling exists.

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