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

Beyond annotations, the description discloses that the tool starts a pre-submission preview, returns a review_id immediately, takes a few minutes, and must be polled with get_manuscript_review. It also mentions rate limits ('limited number of previews per day'), idempotency ('same text and target journal returns the same review'), and output constraints ('report status only; do not add a preliminary critique'). This adds substantial behavioral context.

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 front-loaded with the primary use case and then efficiently covers required content, exclusions, return behavior, retrieval, rate limits, and idempotency. Every sentence adds actionable information; there is no filler.

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?

Despite complexity (async processing, idempotency, rate limits, output constraints), the description covers all essential aspects an agent needs to invoke and follow up correctly. An output schema exists, and the description appropriately does not duplicate return fields, instead focusing on behavioral guidance.

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 the baseline is 3. The description adds meaningful detail for manuscript_text: it must be the complete manuscript text, not a summary, including title, abstract, every section, figure legends, and references. It also implies target_journal participates in idempotency, but does not further elaborate on that parameter beyond the schema.

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 states a specific verb and resource: 'review, check or assess a scientific manuscript' and clarifies it is for when the full text is available but the file cannot be passed. It explicitly distinguishes from sibling review_manuscript (file-based) by saying 'cannot pass the file itself' and from writing/editing tasks with 'Do not use it to write, rewrite or edit text.'

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 when-to-use conditions ('when the user wants Manusights to review... and you have its full text') and explicit when-not-to-use ('Do not use it to write, rewrite or edit text'). It names the alternative for retrieving results ('read it afterwards with get_manuscript_review') and states that figures are not reviewed, so the user must be told.

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