Manusights

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

Beyond the annotations (readOnly, openWorld, non-destructive), it discloses the data sources (Crossref, DOI registry, Retraction Watch, Semantic Scholar, PubMed, arXiv, Open Library), that the manuscript itself is not sent, that DOI-bearing refs are matched by DOI+title only, and that a mismatched expected_reference_count halts the check before lookup.

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 use case and every sentence carries operational content, but it is delivered as a single dense block mixing calling instructions, data-source disclosure, and reporting rules, which would read better split into short sections.

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?

For a read-only, paginated batch lookup with an output schema, the description covers input shaping, batching/continuation, source coverage, input privacy, and reporting discipline; return values are correctly delegated to the output schema's how_to_report.

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 already 100%, but the description adds rationale the schema lacks: send citations verbatim without correcting them, include title so a broken DOI can be distinguished from a missing work, up to 100 per call, one reference per line for reference_list, and never shrink expected_reference_count to fit a shortened input.

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 precise verb+resource (check references/citations) and enumerates the input source types it accepts (manuscript, bibliography, literature review, earlier AI answers). It also names the outcomes it reports (exists, points to right paper, retracted/corrected/flagged), which no sibling tool covers.

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?

Gives explicit triggers with example user questions ('are these references real?', 'is this DOI right?') and explicit exclusions: 'Do not use it to find new sources, to format citations, or to judge whether a source supports a claim.' It also routes between the two input modes (items vs reference_list) and prescribes the start_at continuation loop.

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

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

Beyond the read-only annotations, the description discloses the return behavior: rules come from the publisher's policy page with URL and last-checked date, and unresolved or overdue cases return the URL instead of rules. It also mentions the supplementary submission-to-acceptance metric when available.

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 usage trigger, then covers return behavior, fallback behavior, extra output, input form, and exclusions. Each sentence contributes operational information with 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?

Annotations and output schema already cover safety and return structure, and the description adds enough operational context about fallbacks, source URL, checked date, and supplementary metrics. An agent should be able to invoke and interpret this tool correctly.

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% and the schema already explains that the single parameter accepts an exact journal name or ISSN, with examples. The description reinforces this but does not add syntax or format meaning beyond the schema, so the high-coverage baseline of 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 states a specific verb and resource — retrieving a named journal's recorded AI policy — and enumerates the policy areas covered. It also explicitly distinguishes the tool from unrelated queries such as word limits, formatting, fees, and impact factors.

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 an explicit trigger: use when the user asks what a named journal or publisher allows or requires about AI. It also gives an explicit exclusion list, so an agent can route adjacent questions elsewhere without inference.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavior beyond them: the preview/Full-Review tiering, the 'processing' status with check_again_after_seconds polling, and an instruction not to invent critique or fixes when reporting. The only gap is that it never states whether a Full Review costs quota or requires an entitlement check, which is implied by 'if the account has one' but not explained.

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 purpose, then the polling rule, then the reporting constraint, then the exclusion — a sensible order with no filler sentences. It is somewhat dense, packing four distinct obligations into one paragraph, but every clause carries operational meaning.

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 tool is a single-parameter read with an output schema, so return-value documentation is unnecessary; the description nonetheless explains the preview.status field and the 'processing' vs 'ready' branches, which is exactly the context an agent needs to drive the polling loop correctly.

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% and there is a single parameter, so the schema already carries the type and length bounds. The description adds real value by specifying provenance constraints on review_id (must come from a sibling tool and must be user-referred) plus that the same ID is reused across polling calls.

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 ('read') and resource ('preview, and the Full Review') for a review_id, and explicitly scopes the source of that ID to review_manuscript or list_manuscript_reviews. An agent can distinguish this from the sibling list_manuscript_reviews (which enumerates) and review_manuscript (which creates) without opening any schema.

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 an explicit positive trigger (review_ids returned by the two sibling tools), an explicit exclusion ('Do not use it for review_ids the user has not referred to'), and a concrete retry procedure for the processing state. Nothing about when to call versus call again is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral detail beyond that: the result set is capped at the 20 most recent and ordered newest first, which tells the agent what it will and won't see.

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?

Two short sentences with zero filler: the usage trigger comes first, then the return behavior. Nothing is repeated from the title or annotations.

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?

An output schema exists, so return-value explanation is not required, and the no-parameter signature is fully specified. The one residual gap is that the description does not say whether older reviews beyond the 20 are retrievable by any other means, which matters given the hard cap.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema itself is trivially complete.

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 ('List ... Manusights reviews') and scopes it to the user's own earlier reviews, which is clear. It does not explicitly differentiate itself from the sibling get_manuscript_review (singular), so an agent must infer that this is the bulk/overview variant.

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 an explicit trigger condition: 'Use this when the user asks about their earlier Manusights reviews.' That is a clear usage context, but it names no exclusions or alternatives, so the agent is left to guess when get_manuscript_review is the better call.

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

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

Goes well beyond the annotations: it discloses the asynchronous pattern (returns review_id immediately, preview takes minutes), the per-account daily preview limit, and the idempotency rule (same file + target journal returns the same review). These are exactly the behavioral traits an agent needs and that readOnlyHint/openWorldHint/idempotentHint alone do not convey.

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 trigger and the async contract, and every sentence carries useful information (formats, limit, dedupe, follow-up, exclusions). It is dense but not padded; only minor tightening would be possible.

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?

For an async, rate-limited, idempotent tool with a nested file object, the description covers the full lifecycle: trigger condition, immediate return value, retrieval step, throttling, and dedupe. Output schema and annotations cover the rest, so nothing an agent needs to call it correctly is missing.

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 the baseline is 3. The description adds real value by naming supported formats and the 50 MB size limit for the manuscript object, and by explaining that target_journal participates in the idempotency key — semantics the schema does not state.

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+resource (start a pre-submission manuscript preview) and precisely distinguishes it from get_manuscript_review, which reads the result. An agent can tell what this tool does and what it does not (writing/editing, figures, data files) without opening the schema.

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?

Gives explicit when-to-use (user attached a manuscript and wants a review), the follow-up action (get_manuscript_review with the same review_id), and explicit when-not-to-use cases. It also routes the agent to the correct behavior during processing (report status only, no preliminary critique).

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

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.