download_batch

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

With no annotations, the description carries the full burden and delivers: it discloses failure semantics (partial on some failures, failed on all), the id vs actual_id distinction, cooperative cancellation on caller disconnect, and live progress notification via injected MCP Context. This is far beyond what the schema provides.

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 core purpose is front-loaded in the first sentence and no sentence is filler, but the body is dense with stacked parentheticals, making it longer than strictly necessary for scanning.

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?

An output schema exists, so return values need not be explained, yet the description usefully clarifies the partial/failed status semantics and the item id mapping. Coverage is broad (concurrency, failure modes, cancellation, alternatives) with only minor gaps such as permissions/auth context.

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. It explains the non-obvious concurrency params well (album_workers default 3 and album-only; photo/image_workers and their inherited defaults), and gestures at kind (album/photo) and export_formats (zip/pdf/long_img). ids is left implicit, so it is strong but not complete.

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 ('有界批量下载并等待整批结果') plus the supported kinds (album/photo) and export formats, making it clearly distinguishable from the single-item siblings download_album/download_photo and the async 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?

Explicitly names the alternative and the selecting condition: '适合短批次；需要提前拿到 task_id、轮询及主动取消时使用 start_download.' This tells the agent both when to use this tool and when to route elsewhere.

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