原生商品推广报表下载（不改投放）

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which the description reinforces ('只读报表', '不改预算出价'). Beyond that, it discloses timeout limits, polling intervals, recovery from same taskId/outDir, file contents (missing rows not zero-padded, creatives excluded), and runtime dependencies (python openpyxl/xlrd). This is a rich behavioral disclosure that goes well beyond the annotations.

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 a single dense paragraph but is reasonably sized for the amount of information it conveys. The main purpose is front-loaded, and each sentence adds meaningful content (modes, timing, recovery, file details, dependencies). However, it could be better structured with separators or bullets for clarity, but it is not overly verbose.

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 the tool has 10 parameters (1 required) and no output schema, the description covers the core workflow: what files are produced, mode-specific behaviors, timeout/recovery, and data exclusions. It does not explain all parameters or authentication requirements, but for an export tool the essential usage context is present. Minor gaps in parameter explanation prevent a perfect score.

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 only 30%, and the description does not compensate. It mentions 'mode' and its variants, and indirectly references taskId/outDir for recovery, but fails to explain adId, date, endDate, cdpUrl, maxPolls, expectedMallId, or their roles. With such low schema coverage, the description should have detailed each parameter, but it leaves most of them undocumented for the agent.

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 tool generates read-only report tasks and downloads raw XLS/XLSX, parses JSON and manifest files, and explicitly notes it does not modify budget/bids. It distinguishes itself from sibling tools like pdd_promotion_operations (which implies mutations) and pdd_promotion_data (which likely serves data views). The verb-resource pairing 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 detailed mode guidance (shop-hourly, unit-hourly, unit-daily) with timing expectations and recovery behavior, and notes exclusions (creatives not included). However, it does not explicitly name alternative tools or state when this tool should be avoided in favor of another, leaving some inference to the agent.

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