PubMed Scraper: Articles, Abstracts & Evidence Table to Excel

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), and the description still adds genuinely new operational facts: it runs a named Apify Actor on the caller's own account, charges $0.004 per article found, gives free runs that find nothing, and enforces a per-call spend cap via run_max_charge_usd. The cost and billing model is the key thing an agent could not infer from annotations. It does not explain how the Excel artifact is delivered back, which stays opaque.

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 tight paragraphs with an explicit Input/Output structure, front-loading the purpose before the billing details. The Actor URL is arguably filler for an agent, but otherwise every sentence carries information.

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 18-parameter, no-output-schema tool, the description does the important work: it names the output columns, mentions PRISMA counts and the Excel deliverable, and explains the cost model. The remaining gap is how the returned Excel file is accessed, which an agent needs in order to complete the workflow.

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 parameters are already documented, and the description only summarizes them at a high level ('query strings plus optional date and study-design filters'). The one linkage it surfaces, that spending is capped per call by run_max_charge_usd, is also stated in the schema for maxResults and run_max_charge_usd. Baseline 3 is appropriate here.

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 resource ('search PubMed and get a screening-ready evidence table') and enumerates the return columns (PMID, journal, study design, sample size, retraction status, PRISMA counts, Excel). This is far more than a restatement of the title. It never names the overlapping siblings literature_search or citation_formatter, so an agent must infer which one to pick.

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?

'Use this to search PubMed and get a screening-ready evidence table' implies the use case (systematic review screening) but gives no explicit when-not or routing to alternatives. With siblings like literature_search and citation_formatter in the same family, the absence of differentiation is a real gap.

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