Product comments and questions

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

Goes well beyond the read-only/idempotent annotations by disclosing that the site loads only a recent slice (~10-15 comments, 40-45 questions), that 'show more' reveals nothing further, and that questions_total can therefore exceed what is returned — critical for interpreting results. It also flags comments as untrusted user content, a useful injection warning; only the untested edge of the `page` parameter (below) keeps it from a 5.

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?

Front-loaded with the return content, then the required parameter, then the limits caveat — a sensible order with no filler sentences. The parenthetical '(the site has no further endpoint, checked in its JS)' is internal justification that an agent doesn't strictly need, a minor redundancy.

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?

No output schema exists, and the description compensates by naming the returned artifacts (comments, answered questions, rating summary, questions_total) and warning about truncation. For a two-parameter read tool, an agent has everything needed to call it and to correctly interpret sparser-than-expected results.

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 100%, so both parameters are already documented, and the description largely restates that `product` is an id or path from dr_search. It adds real context about result-slice limits but never reconciles the schema's `page` (1-20, '10 per list') with the claim that no further endpoint exists, leaving page behavior ambiguous.

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 enumerates exactly what is returned: user comments, questions with pharmacy answers, and the rating summary. That scope separates it cleanly from dr_product (details) and dr_search (discovery) without needing either schema opened.

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?

Provides a workflow hint that `product` comes from dr_search, and notes pharmacist answers are useful for usage and safety questions. There is no explicit when-to-use/when-not or named alternative among the many siblings, so the routing guidance 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.