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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: pre-indexed text, page numbers, exact product matches, and one excerpt per product. No contradiction is present.

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?

One dense sentence covers both modes, their inputs, and their outputs without wasted words. The primary 'ask a datasheet' behavior is front-loaded and the alternative is clearly separated.

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?

The two modes and their output content are described, which is helpful since there is no output schema. However, the required parameter groupings are not stated explicitly — for example, whether the single-datasheet mode needs both q and product_id, while the scan mode needs term and category.

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?

q and term already have schema descriptions, and the description reinforces the term + category relationship for the scan mode. However, product_id is undocumented in the schema and the description never explains how it selects the target datasheet, leaving some parameter semantics implicit.

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 two distinct behaviors: asking a single product datasheet a question and getting closest excerpts with page numbers, or scanning all datasheets in a category for an exact term. It is specific about the verb and resource, but it does not explicitly position itself against sibling tools like search_datasheet_facts.

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 gives clear context for when to use each mode: a question about one datasheet versus an exact-term scan across a category. It does not name alternatives or exclusions, but the two-mode structure makes the usage conditions reasonably clear.

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