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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape (one line each with author id, name, works count, citation count) — meaningful since there is no output schema. It doesn't mention result limits or ranking among candidates, which 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 purpose and return format, then inputs and an example — well ordered with no fluff. The final example prompt largely restates the opening intent, a minor redundancy rather than a defect.

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 one-parameter lookup with no output schema, the description covers purpose, next step, and the fields returned per result line. The remaining gap is how many candidates come back and how ties are ordered, which matters for a disambiguation tool.

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 single parameter is documented there with the same 'Jane Doe' example, so the description's restatement of name as required adds little. The mention of matching behavior ('candidate authors matching a name') hints at partial-match semantics but doesn't specify matching rules. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('candidate authors matching a name') and immediately frames the intent: pick the right one before listing their papers. That explicitly distinguishes it from the sibling list_author_papers, so an agent can route between the two 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?

The workflow context ('so you can pick the right one before listing their papers') plus the example prompt makes the intended call sequence clear. It stops short of naming explicit exclusions or prerequisites, but the disambiguation-first framing gives strong usage signals.

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 openWorldHint=true. The description adds useful behavior beyond that: results are ordered newest first, each carries a one-line abstract, and a separator line summarizes the page and total count. It doesn't cover error behavior or rate limits, but with annotations carrying the safety profile this is strong.

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 behavior, then pagination details, then inputs. Four sentences plus an example are reasonably tight, though the inputs list redundantly repeats the schema's parameter descriptions.

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 describing the return shape (one-line abstract per result, showing line with page/total info) and how to paginate. Combined with full schema coverage and annotations, an agent has everything needed to invoke it 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 description coverage is 100%, so the schema already documents all three parameters fully. The description's inputs section largely restates the schema (paper formats, page range, limit range) without adding new syntax or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (lists) and resource (papers that cite a given paper), plus ordering (newest first). Explicitly distinguishes itself from sibling paper_references as 'the other half of the citation graph,' so an agent can route correctly 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?

Explains when to use it (walking the citation graph in both directions for a literature review) and names the complementary sibling tool explicitly. The example prompt ('who cited DOI ...?') reinforces the use case.

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 (readOnlyHint, openWorldHint), and the description adds real behavioral value beyond them: it prefers PDF over landing page and degrades gracefully ('says so in plain words instead of failing'). It stops short of describing where copies come from or what fields the response carries.

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 outcome and preference rule, then inputs and an example. Only the restated input formats duplicate the schema; everything else earns its place.

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 one parameter and no output schema, the description covers the essentials an agent needs: what comes back (a link, PDF preferred) and what happens on no-result (plain-words message). A short note on what the plain-words response looks like would close the last gap.

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 description repeats the accepted identifier formats verbatim from the schema, so it adds little new semantic detail. The example prompt is marginally useful but doesn't explain normalization or error behavior for malformed IDs.

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 ('Finds a free to read copy of one paper and returns the link') plus a preference rule (PDF over landing page). This clearly separates it from siblings like get_paper (metadata) and search_papers (discovery).

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?

The framing ('free to read copy') plus the example prompt gives an agent a clear trigger condition. It doesn't explicitly name an alternative such as get_paper, so the when-not 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.

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

Annotations already cover safety (readOnlyHint) and scope (openWorldHint), yet the description adds genuine behavioral detail: every result carries a one-line abstract, and a 'showing line' reports the current page, the total related-paper count, and the next page token. That is useful return-shape context given there is no output schema. It does not cover failure modes for malformed or unresolvable identifiers.

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 core purpose, then value proposition, then pagination behavior, then inputs and an example. It is a bit run-on in a single block and restates the page/limit ranges already in the schema, which is 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?

With no output schema, the description fully compensates by describing result contents (one-line abstract) and the pagination envelope (current page, total count, next page). Identifier formats, defaults, and caps are all present, so an agent can call and interpret this correctly without opening anything else.

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 earns above baseline by explaining the interaction between the page parameter and the 'showing line' output ('Pass the page the showing line names'), which is not in the schema. The paper identifier formats are repeated from the schema but reinforce the accepted DOI/URL/OpenAlex-id variants inline.

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 ('Lists the papers that OpenAlex lists as related to a given paper') and scopes it to topical similarity, which meaningfully distinguishes it from siblings like find_citing_papers and paper_references. It never names those siblings explicitly, so the differentiation is implied rather than stated.

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 a clear motivating use case ('find more work on the same topic') and a concrete example prompt anchoring invocation. It stops short of saying when NOT to use it or pointing to find_citing_papers/paper_references as the alternative for citation-based discovery.

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 and openWorldHint, so safety is covered; the description adds real behavioral detail beyond that – the not-found error path and its suggested remedy, plus the precedence rule that 'paper wins if you give both' inputs. It lacks anything about rate limits or whether the free-to-read link can be stale, but the operational contract for a lookup tool is well disclosed.

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 value, then inputs, then a worked example – a sensible ordering with no wasted framing sentences. The trailing 'Example prompt' quote is mild filler that restates the DOI format already given twice.

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 summarizing the returned payload (abstract, free-to-read link) and the failure mode. Complete enough to call correctly; the only residual gap is none of it clarifying overlap with find_open_access_pdf.

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 would be 3, but the description adds semantics the schema does not: the conflict-resolution rule when both arguments are supplied, and a restatement that OpenAlex ids are valid only for 'paper'. That precedence rule is genuinely useful call-time behavior not encoded anywhere in 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?

States a specific verb+resource ('Details for one paper') and enumerates what comes back (abstract, free-to-read link when available), which distinguishes it from list-style siblings like search_papers. It never names an alternative tool outright, so the boundary with find_open_access_pdf in particular is left to inference.

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 concrete input-type guidance (DOI, doi.org link, OpenAlex id) and a routing rule on failure: a not-found error suggests searching by title, which implicitly points at search_papers. It stops short of explicitly saying when to prefer this tool over find_open_access_pdf or paper_references.

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 cover only read-only and open-world, so the description carries the rest and does: it discloses the two-stage author resolution (OpenAlex author records first, name-on-paper fallback), the citation-descending ordering, and the 'showing line' pagination contract. That is behavior an agent cannot get from the annotations.

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, ordering, and resolution behavior, and the example prompt earns its place. The enumerated 'Inputs:' block duplicates the schema and is the main slack in an otherwise well-ordered description.

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 no output schema, the description still explains the return shape (per-page listing plus total matched and next page) and the fallback matching path. Nothing essential for correct invocation is missing for a 7-parameter read tool.

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 every parameter is already documented, and the description's trailing 'Inputs:' list largely restates ranges and defaults. It adds only marginal value, such as the concrete 'Jane Doe' / 'A5108843829' author forms and the hint to pass the page from the showing line.

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 resource and scope up front ('Papers by one author, most cited first'), which immediately separates it from find_authors (person lookup) and search_papers (topic search). The verb and result ordering are both explicit.

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 clear context for when this tool applies (you know an author name or OpenAlex author id) and includes a concrete example prompt. It never names a sibling tool or states when to prefer search_papers/find_authors instead, so it stops short of full when/when-not guidance.

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 openWorldHint=true, so safety is covered. Beyond that, the description discloses meaningful behavior the annotations do not: every result carries a one-line abstract, and a 'showing line' reports which references are on the page, the total the paper lists, and the next page to request. It does not cover error behavior for invalid DOIs, which is the main remaining gap.

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 narrative portion is front-loaded and useful, but the trailing 'Inputs:' block and example prompt duplicate the JSON schema almost verbatim (limits, defaults, enum values), which is wasted space. Roughly a third of the text earns nothing beyond what structured fields already provide.

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 paginated read tool with no output schema, the description supplies what an agent needs: what each result contains (abstract), how pagination is surfaced (showing line with total and next page), and how to continue. Only failure modes and empty-result behavior are unaddressed.

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 all four parameters are already documented in the schema. The description's 'Inputs:' section restates the same ranges, defaults, and accepted identifier formats without adding new semantics. Baseline 3 applies since the schema, not the description, carries this dimension.

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 ('papers that one paper cites') and immediately defines itself against the sibling that covers the inverse direction ('the other half of the citation graph that find_citing_papers covers'). An agent can distinguish this from find_citing_papers 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 three concrete usage scenarios (read a bibliography, trace a result's source, work backwards to earlier work) and names the sibling alternative plus the condition that separates the two. It lacks an explicit 'do not use this when...' exclusion, but the routing guidance is clear.

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 only declare readOnlyHint and openWorldHint; the description goes well beyond them by specifying the exact return fields (title, authors, year, venue, citation count, DOI, one-line abstract, free-to-read link) and by explaining the result-counting line and page-following mechanism. It stops short of covering failure modes, empty-result behavior, or source/rate-limit characteristics.

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 purpose and return shape are correctly front-loaded, but the single dense paragraph drifts into awkward phrasing ('a showing line under the heading says which results are on this page') and then duplicates the entire input schema parameter-by-parameter. The trailing enumeration of Inputs: is the least earning part of the text.

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 no output schema and ten parameters, the description carries the return-value burden and does so adequately, including pagination semantics and the page cap. Gaps remain around empty results, matching behavior for the query string (boolean/phrase support), and error handling, but nothing essential for a correct call 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 description coverage is 100%, so all ten parameters are already documented with ranges, enums and defaults. The description's parameter recap largely restates the schema, adding only light intent framing ('so you can get the most cited papers on a topic or the newest ones'), which earns baseline rather than above-baseline credit.

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 ('Search scholarly papers by keywords') and immediately enumerates what comes back, which distinguishes it from siblings like get_paper, find_citing_papers and find_related_papers that operate on an already-known paper. An agent can tell this is the discovery entry point 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?

Usage is implied by the firehose-style filtering options and made concrete by the closing example prompt ('find the most cited papers on spaced repetition since 2020'). However, it never states when NOT to use this tool or names an alternative sibling (e.g. 'once you have a DOI, use get_paper'), leaving the agent to infer the search-then-fetch pattern.

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