books

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

With no annotations, the description carries the full burden, and it does well: it discloses the failure contract (status=NO_DATA/PARTIAL with per-item diagnostics and an action plan) and explicitly says it will not fake success. It also constrains scope and repeats that login/paywalls are not bypassed. It stops short of stating auth requirements or the mechanism behind the interval-based throttling.

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?

It leads with the core action and then lists the outputs, and every clause in the one-block description earns its place: scope, exclusion, exports, and failure semantics. It is dense but not padded.

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?

There is no output schema, yet the description names the exact returned files and the NO_DATA/PARTIAL status values, so an agent can anticipate the return shape. Combined with schema-covered parameters, an agent has nearly everything needed to call it, though it does not describe the spec JSON contract or how covers are stored.

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 all five parameters, including the nested spec object, are already documented in the schema. The description adds domain color (comparing JD and Dangdang, exporting booklist.csv/md/json) but no syntax or format guidance beyond what the schema provides, so the baseline 3 applies.

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 names a specific verb and resource: it collects book-catalog data from an ISBN list (Douban ratings, author, publisher, JD+Dangdang price comparison) and exports four named file types. That detail differentiates it sharply from generic siblings such as scrape, crawl, and bulk_scrape, which do not mention books or export formats.

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 states the input shape context (an ISBN list) and the output artifacts, plus clear scope exclusions: no e-book/PDF downloading and no login or paywall bypass. It does not explicitly say when to prefer this over scrape or bulk_scrape, so the sibling routing is implied rather than stated.

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