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

Annotations only cover the read-only/open-world profile; the description adds substantial context beyond that: price ($0.003 per formatted citation), what is not billed (unresolved items, empty runs), a per-call spending cap via run_max_charge_usd, expected latency, and that bibliography files are written to the run's Apify key-value store rather than returned inline. It also discloses the minMatchScore resolution rule (exact for DOIs/IDs, fuzzy for text).

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?

Structure is excellent — purpose, differentiation, cost, latency, return shape — and the routing guidance is front-loaded. There is some avoidable repetition: 'Only formatted citations are billed' appears twice, and 'all styles are one price' duplicates the styles field text, which costs it the top score.

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 14-parameter, zero-required-parameter actor wrapper with no output schema, the description is thorough: it describes the return envelope ({actor, count, items}), lists per-item fields, notes truncation behaviour and structuredContent, and covers pricing, caps, and timeouts. An agent has everything needed to size, budget, and interpret a call.

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 earns extra by explaining cross-parameter interaction that the schema only hints at — run_max_items also limits what is billed and 'fills maxReferences when you leave it unset, so setting maxReferences higher can bill more than is returned'. It also states run_timeout_secs should be raised after timeout errors. Minor gap: it does not restate what minMatchScore or listUnresolvedInFiles do beyond the field docs.

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 opening sentence names a specific verb (Convert) and enumerates the accepted inputs (DOIs, ISBNs, PMIDs, arXiv IDs, titles, messy strings) and outputs (APA 7, MLA 9, Chicago, Harvard, IEEE, Vancouver, BibTeX, RIS). It explicitly distinguishes itself from reference_checker ('formats rather than audits') and literature_search, so an agent can route correctly 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 positive triggers ('Use when you need a clean bibliography or .bib/.ris export') and explicit exclusions with named alternatives ('Do not use to find papers (use literature_search) or to prove references are genuine (use reference_checker first)'). It also advises on call batching (request every style in one call) and on timeout recovery.

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 read-only, open-world and non-destructive status, but the description adds substantial context they cannot express: per-paper pricing ($0.003), spending caps, the 5-15 s vs. minutes runtime split, timeout remediation, and that output is trimmed to whole items with all items in structuredContent. The only gap is that it does not discuss failure/error surfaces beyond timeouts. Note that the parameter-recap sentences largely restate schema text rather than adding new behavioral facts.

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 correctly: purpose, differentiation and when-to-use come before parameter detail and the behavior block. It is long for a single field, and the parameter recap in the first paragraph re-treads schema content (sortBy ordering, retraction billing, readingListSize cost) that an agent has already been given, which is the main source of bloat.

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?

With 21 optional parameters and no output schema, the description compensates well by listing the per-item return fields (summary, readingRank, pdfUrl, retracted, citation, bibtex, ris, abstract) and the {actor, count, items} envelope. Cost model, timeout guidance and the seed-network semantics complete the picture an agent needs before calling.

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 schema already documents cost caps, billing for maxResults, retraction billing and dataset ordering, and much of the description's parameter walkthrough duplicates that. It does still add genuine cross-parameter meaning: that seedDois alone walks the network while a query searches within it, and that searchIn=fullText trades precision for recall. That added interaction semantics lifts it above the baseline 3.

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 ("Search"), resource ("250M+ scholarly works (OpenAlex)") and source mode ("topic query or seed DOIs"), then enumerates what comes back (DOI, citation count, free PDF link, retraction flag, ready citation). It explicitly contrasts itself with pubmed_evidence_table and researcher_expert_finder, so an agent can separate it from siblings without opening a 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 positive triggers ("real papers on a topic, a reading list, or papers citing/cited by known DOIs") and explicit exclusions with the sibling to use instead ("Do not use for systematic biomedical screening... or to find people"). It also explains the mode-selection rule for seedDois with vs. without a query, which is the main routing decision an agent must make.

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 supplied annotations (readOnlyHint/openWorldHint/destructiveHint), disclosing the full cost model ($0.001/page, $0.003/table, $0.02/OCR page), the hard cap via run_max_charge_usd, the 150 MB failure-and-no-charge rule, and the 5-15 s typical / 300 s max runtime with timeout remediation. It also warns that OCR is slow and error-prone on digits. This is exactly the context annotations cannot carry.

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 purpose, differentiation, and use/don't-use routing before the operational detail, which is the right order. It is long but nearly every sentence carries distinct information; the main waste is pricing stated twice (prose 'billing is per page analysed plus per table extracted' then the explicit price list) and the run_max_items caveat repeated.

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?

With 15 optional parameters and no output schema, the description carries the burden well: it describes the return payload ({actor, count, items}, per-item summary/pages/header/row and column counts/cell data), notes that Excel/CSV artifacts remain in the run's key-value store, and mentions structuredContent trimming. An agent has enough to call it correctly and interpret the result without an output schema.

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%, yet the description adds cross-parameter meaning the schema cannot: which knobs actually drive cost ('pages and maxPagesPerPdf are the real cost levers'), that OCR cost scales up to maxOcrPagesPerPdf, and the detection-mode decision rule. It loses a point for conflicting with the schema on run_max_items, which the description says 'does not limit what the Actor bills' while the schema says it 'also limits how many results the Actor produces and charges for.'

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 opening sentence gives a specific verb and resource ('Extract every table from PDF files ... into structured rows, Excel and CSV, with optional OCR'), plus both input sources (URL or Apify key-value store). It explicitly differentiates from named alternatives ('Unlike sec_financials_excel ... this reads whatever tables a PDF contains') and names literature_search, so an agent can place it against siblings 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?

States the positive case ('Use when the data you need is locked in PDF tables: reports, statements, government releases') and two explicit exclusions with redirects ('Do not use for SEC-listed company financials (use sec_financials_excel) or to find papers (use literature_search)'). It also gives conditional selection guidance inside the tool, e.g. 'force lattice or stream only if auto merges or splits columns.'

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 read-only, non-destructive, open-world, non-idempotent, so the description focuses on what annotations cannot carry: per-article pricing, which filters are applied before billing, that PRISMA counts still report removed records, the run_max_items vs maxResults billing interaction, the 300s timeout ceiling, and that long text output is trimmed to whole items. The only gap is no statement about how failures or partial results surface beyond the timeout hint.

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 purpose, then alternatives, then parameter behavior, then runtime/cost — a sensible order for an 18-parameter tool, and nearly every sentence carries information. It is long and repeats billing language already present in the maxResults and retractedArticles schema descriptions, which costs it a point.

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 tool with no output schema, the description supplies the return field list, the envelope shape {actor, count, items}, the structuredContent trimming rule, latency expectations, and where Excel/PRISMA/RIS artifacts are stored. Combined with full schema coverage and annotations, an agent has everything needed to call it and interpret the result.

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 baseline is 3, but the description adds genuinely non-obvious semantics: queries accept field tags and are de-duplicated across queries, retractedArticles=flag bills flagged rows while exclude does not, and sampleSizeConfidence should be treated as unverified at low values. The subtle warning that raising maxResults can bill more than run_max_items returns is the kind of interaction the schema alone cannot convey.

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?

Specific verb and resource: 'Run one or more PubMed queries and return a screening-ready evidence table', with the row schema (PMID, journal, study design, sample size, retraction status) enumerated. It explicitly distinguishes itself from literature_search, clinical_trial_leads and reference_checker by scope and data source, so an agent can route between them without opening a 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?

States the positive condition ('biomedical/clinical and you need reproducible PubMed queries or design filters') and four explicit when-not cases with the sibling to use instead. Nothing about selection 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, openWorldHint=true, destructiveHint=false and idempotentHint=false, and the description is consistent with all of them ('read-only'). It adds real value beyond them: the Apify actor and account it runs under, $0.01-per-reference billing, the run_max_charge_usd cap, that finding nothing is not charged, timeout behavior (5-15 s typical, raise run_timeout_secs to 300), and that monitor mode persists state in a key-value store. That is substantive operational context, though it is packed into a single dense block rather than organized by concern.

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?

Purpose and sibling differentiation are front-loaded, followed by usage, then parameters, then runtime/billing behavior, then return shape — a sensible ordering. The prose is dense but nearly every sentence carries non-obvious information (billing mechanics, monitor state, timeout escalation) rather than restating the schema.

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 14-parameter, zero-required, billed, open-world tool with no output schema, the description covers what an agent needs: at least one of bibliography/dois/titles is required, cost and cap mechanics, timeout escalation, persisted monitor state, and an explicit per-item return field list (status, verdict, matchedDoi, matchScore, mismatches, integrity.status, openAccessUrl, warnings). Little is left to inference.

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 schema already documents all 14 parameters and the baseline of 3 applies. The description does add cross-parameter meaning the schema cannot: lowering minMatchScore trades recall for false matches, includeCandidates is free, run_max_items fills maxReferences when unset, and setting maxReferences higher can bill more than is returned — genuine semantic value, but scattered and not systematic.

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 opening sentence gives a specific verb and resource ('Verify an existing bibliography against Crossref') plus the failure classes it detects (fake/hallucinated, miscited, retracted) and the output shape ('one row per reference'). It then explicitly contrasts itself with citation_formatter ('judges whether a reference is real and accurate; it does not produce formatted styles'), so an agent can separate it from siblings without reading schemas.

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 states the trigger ('Use when you must audit a reference list, DOIs or titles before submission or review') and both exclusions with named alternatives: discovery goes to literature_search or pubmed_evidence_table, restyling goes to citation_formatter. Monitor-mode usage (reuse the same monitorName on scheduled runs) is also specified.

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 read-only and non-destructive, so the description correctly spends its words on what the annotations cannot say: the Apify Actor it runs, $0.0025 per expert pricing, the no-charge-on-empty-runs rule, the per-call spending cap, and realistic 5-15 s latency with timeout remediation. It also clarifies the run_max_items / maxResults billing interaction, which is a genuine behavioral gotcha.

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 purpose and sibling differentiation before mechanics, and every section (use, don't use, params, behavior, returns) is labeled implicitly by position. The parameter recap paragraph is somewhat long given 100% schema coverage and repeats a few schema facts, which keeps it from a 5.

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 tool with no output schema, the description supplies the return envelope ({actor, count, items}), the per-item field list (score, ORCID, institution, h-index, recent papers), and the structuredContent trimming behavior. Combined with cost, latency, and timeout guidance, an agent has everything needed to call it and interpret 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 the baseline is 3; the description earns above that by adding cross-parameter semantics the schema does not spell out, notably that the ranked pool is capped at 200 authors so maxResults above 200 adds nothing, and that run_max_items fills maxResults and therefore bounds billing while a larger maxResults can bill more than is returned. The yearFrom/yearTo-vs-activeSince and maxAuthorsPerPaper notes largely restate the schema, so this sits at 5 rather than higher.

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?

Opens with a specific verb and resource ("Rank the academic experts and key opinion leaders on a research topic from OpenAlex") and immediately disambiguates against the sibling literature_search ("returns people" vs "returns papers"). An agent can pick this tool without opening either 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 concrete use cases (reviewers, KOLs, collaborators, speakers), states the optional country/institution dimension, and adds explicit exclusions with named alternatives ("Do not use for company contacts (use company_team_finder) or for papers themselves (use literature_search)"). Nothing 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.