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

With no annotations, the description carries the full burden and does so: it explains the phrase-matching workaround, warns the result is a sample of top relevance hits rather than a complete count, notes older years may be under-represented, states larger scan is slower but more complete, and clarifies counts describe metadata only, not quality. These are exactly the caveats an agent needs before relying on the numbers.

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 sectioned (purpose, when to use, how it works, args, returns) and front-loaded so the highest-value information comes first. It is somewhat long and the Args/Returns blocks partially restate the schema/output structure, but nearly every line carries usable 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 a 5-parameter aggregation tool with no annotations, the description covers purpose, usage, mechanism, limitations, all parameters, and a return-shape sketch (which is welcome even alongside the output schema). 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 description coverage is 0%, so the description must compensate, and it documents every parameter: phrase (case/hyphen-insensitive), scan (100-2000, default 500, with a speed/completeness tradeoff), from_year/until_year as bounds, and work_type as a Crossref type with an example value. This adds semantics the bare schema lacks.

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 first line states a specific action and its outputs (per-year counts, top venues/publishers/funders, most-cited works) gated on exact-phrase title matching. The 'How it works' note that Crossref lacks phrase search and that this scans top relevance hits distinguishes it from a plain search sibling. An agent can separate it from search_crossref or find_related_works 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?

It gives explicit when-to-use scenarios (trend questions, thesis background, venue/funder landscape) with example phrasings. What it lacks is a negative statement routing the agent to an alternative (e.g., 'for a plain keyword search use search_crossref'), so context is clear but no exclusions are 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?

No annotations are provided, so the description must carry the full behavioral burden, and it does well: it discloses the DOI content-negotiation mechanism, that it covers both Crossref and DataCite DOIs (arXiv, Zenodo), the max-50 input limit, and a partial-failure result shape. It omits auth requirements, rate limits, and whether failures are retried, which are the remaining gaps.

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 cleanly sectioned into When to use / Args / Returns / Example. Every section is useful, though the Returns block partially restates the output schema that already exists, adding a small amount of 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?

For a two-parameter formatting tool with an output schema, the description covers coverage (Crossref + DataCite), the input cap, the failure path, accepted style values, and a worked example. 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 0%, so the description must compensate fully, and it does: 'dois' gets an example list and a max-50 constraint, and 'style' gets a default, an explicit enumeration of common styles, the CSL-style-id escape hatch with a URL, and three export formats.

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 (format/cite) and resource (DOIs/citations) plus scope: any citation style or export format. It is clearly distinct from siblings like resolve_dois (which resolves metadata) and search_crossref (which finds works).

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?

Includes an explicit 'When to use' list with concrete scenarios (building a bibliography, exporting to Zotero/Mendeley/EndNote). It does not, however, name sibling alternatives or state when NOT to use it, leaving the routing to resolve_dois or search_crossref 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?

No annotations, so the description carries the full burden: it discloses the similarity mechanism (text vocabulary/subjects rather than citations) and the response shape (seed + related works with relevance_score). It does not cover failure modes such as an unresolvable DOI or rate limiting, but the core behavioral context is present.

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 one-line purpose followed by clearly labelled When to use / Args / Returns / Tip blocks. The Returns section is somewhat redundant given an output schema exists, but it is short and no sentence is 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?

For a 2-parameter read tool with an output schema, the description covers purpose, triggering scenario, parameter meaning, return shape, and the key sibling alternative. Nothing an agent needs to select or invoke 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 0%, so the description must compensate, and it does: doi is identified as the seed paper's identifier and rows is explained with a range (1-50) and default (10) that the bare schema does not express. Field titles alone would not have told an agent any of this.

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 (find) and resource (works bibliographically similar) and pins down the similarity basis ('same title vocabulary and subjects'), which cleanly separates it from citation-based siblings like snowball_doi.

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?

Explicit 'When to use' scenario ('More like this' from one good paper, without needing references or citations) plus a Tip that names snowball_doi as the alternative and says when it is usually more meaningful. Both the when and the when-not are 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?

With no annotations, the description carries the full burden and does so well: it warns that name matching is fuzzy and namesakes can be mixed in, explains that an ORCID filter removes them and that multiple returned ORCIDs signal a rerun, caps max_works at 20-500, and cautions that counts reflect Crossref metadata rather than research impact.

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 sectioned layout (When to use / Args / Returns) is front-loaded and scannable, and most lines earn their place. The Returns block largely restates the output schema, which is mildly redundant, though it is compact and does add the impact caveat.

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?

Given an output schema exists, return values need not be re-explained; the description instead covers the argument semantics, usage triggers, and the fuzzy-matching/namesake caveats that structured fields cannot convey. Nothing an agent needs to invoke 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 description coverage is 0%, so the description must compensate entirely, and it does: each of the three parameters gets meaning beyond its type, including a concrete name example, the ORCID filtering semantics plus a sample iD, and the max_works range with default.

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 first sentence states a specific verb (build) and resource (author profile from Crossref metadata), enumerating the exact fields produced (publications, co-authors, venues, affiliations, ORCID iDs). This is clearly distinct from siblings like get_crossref_work or search_crossref, which target works rather than people.

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 'When to use' block gives concrete triggering questions ("Who is this researcher / who do they collaborate with?") and the ORCID workflow tells the agent how to iterate when namesakes appear. It stops short of naming alternative siblings or stating when NOT to use this tool, so it falls short of a 5.

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?

No annotations are supplied, so the description carries the full behavioral burden. It implies a read-only lookup and usefully discloses that funding links are 'as declared by publishers', plus the ambiguity signal via 'other_matches', but says nothing about auth requirements, rate limits, or failure behavior for an unknown funder.

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 purpose followed by clearly labelled When to use / Args / Returns sections; every element is scannable. The Returns block is somewhat redundant given a formal output schema exists, which keeps it just short of 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 a 2-parameter, output-schema-backed tool this covers the essentials: what it returns at a glance, parameter formats, and the multi-match case. Missing only the read-only/auth framing that the absent annotations would otherwise have provided.

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 0%, so the description must carry the load and it does: name_or_id is explained as accepting either a funder name or a Crossref Funder ID with a concrete ID example ('501100014538'), and latest is bounded ('0-20, default 5') beyond the bare schema default.

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 ('look up') plus the resource ('a research funder') and its payload ('the works it funded'), and pins the data provenance to Crossref publisher declarations. The funder resource is clearly distinct from the sibling author/journal/work lookup tools.

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?

An explicit 'When to use' block names concrete scenarios ('What has LPDP / NSF / Horizon Europe funded?', grant output tracking, funder landscape). It gives clear positive context but names no alternatives or when-not conditions (e.g. when to use search_crossref instead).

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?

With no annotations, the description carries the full burden and does substantial work: it discloses the two distinct return shapes, the meaning of "coverage" (share of current works with abstracts/ORCIDs/references/licenses), the latest range and default, and a critical caveat that coverage is metadata completeness, not a quality ranking. It omits operational traits such as rate limits or auth, but for a public read-only metadata lookup this is close to complete.

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 one-line purpose, then cleanly sectioned into When to use, Args, and Returns. Every sentence adds information an agent needs (trigger conditions, dual-mode argument behavior, return shapes, the coverage caveat) 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?

For a two-parameter read tool with an output schema present, the description supplies everything an agent needs: when to call it, the dual interpretation of the primary argument, the return structure per mode, and the semantic caveat on coverage. Nothing required to invoke or interpret 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 description coverage is 0%, so the description must compensate fully and it does: issn_or_name is explained with a concrete example ("0957-4174") and the behavioral difference between passing an ISSN versus a name (full profile vs. list of matches), and latest is documented as 0-20 with a default of 5. Both parameters gain meaning absent from 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 opening line states a specific verb (look up) and resource (a journal) and enumerates exactly what is retrieved: publisher, ISSNs, subjects, DOI counts, metadata coverage and latest works. This is clearly distinguishable from siblings like get_crossref_work or get_crossref_author, which operate on works and people rather than journals.

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 explicit trigger phrasings ("Tell me about journal X", "does X deposit abstracts/ORCIDs?") and names a concrete downstream alternative: use the returned ISSN to filter search_crossref by issn. When to use and how it chains into a sibling are both stated rather than 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?

No annotations are provided, so the description carries the full burden, and it does so well: it discloses that resolve triggers extra calls capped at 20 and sorted by citation count, and that only publisher-deposited references exist (some publishers deposit none). It stops short of stating the operation is read-only or describing failure behavior for an invalid DOI.

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 and cleanly sectioned into When to use / Args / Returns / Notes. The Returns block partially duplicates the output schema, which is minor redundancy, but no sentence is wasted.

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?

Given the tool's complexity, the description covers purpose, selection guidance, both parameter semantics, data-availability caveats, and sibling routing, while an output schema already documents the return shape. Nothing essential for correct invocation 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 0%, so the description must compensate, and it does: it explains doi as the citing paper's DOI and fully specifies resolve's semantics (fetch metadata for the first N DOI-bearing references, max 20, sorted by citation count, default 0 = no extra calls). The doi entry is minimal but sufficient.

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 ('List the references (bibliography) of a paper') and immediately clarifies the scope with 'the older works it cites.' It also distinguishes itself from the sibling snowball_doi by declaring the reverse direction is not covered.

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?

Provides an explicit 'When to use' list (backward snowballing, checking relied-on sources) and a 'Notes' section that routes the agent to snowball_doi when the forward-citation direction is needed. Both when-to-use and when-not-to-use are covered.

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?

With no annotations, the description carries the full burden and does so: it discloses that a 404 means Crossref does not know the DOI, that arXiv DOIs are registered with DataCite so this returns 'not found', and that abstract is frequently null due to publisher deposit behavior. It also explains that metadata_quality describes metadata only, never scientific quality — a subtle but important framing caveat.

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 one-line summary, then labeled blocks (When to use / Args / Returns / Tips) that map to the questions an agent actually asks. Each sentence carries distinct information; none restate the name or title.

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 single-param read tool this is complete: input formats, output semantics (metadata_quality with its missing-fields meaning), failure modes, and known data-source gaps are all covered. The output schema handles structure, so the description is free to explain interpretation.

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 0% for the single doi parameter, so the description must compensate — and it does, enumerating accepted spellings ('10.1145/3065386', 'https://doi.org/...', 'doi:10.1145/...') and stating case-insensitivity. This is meaningfully more than the bare 'string' schema field.

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+resource+scope: 'Get the complete, normalized metadata record for one DOI.' It clearly delimits itself from get_crossref_references (reference list) and snowball_doi (alternate abstract source) in the Tips, so an agent can route between siblings without opening 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?

The 'When to use' block gives two concrete triggering conditions (you already hold a DOI; you want to validate a DOI before citing), and the Tips name explicit alternatives and their conditions — snowball_doi for abstracts, cite_dois for arXiv DOIs, get_crossref_references for reference lists.

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?

With no annotations, the description carries the full burden and does well: it discloses the failure mode and its meaning ('Not found' = typo, fabricated, or DataCite-registered), the cap behavior (default 25, max 100), and that dedup applies to unique DOIs. It stops short of stating network/auth behavior or partial-failure semantics beyond the failed list.

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 purpose sentence followed by tightly scoped Args/Returns/Follow-up sections; every block earns its place. The Returns block partially restates the output schema, which slightly blunts conciseness, but the 'Not found' interpretation is genuinely additive.

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 the shape need not be re-explained, yet the description usefully clarifies the meaning of the 'failed' entries and points to the next tool. Coverage is complete for an agent to call this correctly; only edge-case behavior (e.g., partial results on network failure) is absent.

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 0%, so the description must compensate, and it does: text accepts any DOI form ('doi:10.x/y', 'https://doi.org/10.x/y', bare) and max_dois is documented with default and ceiling. Minor gap: no guidance on behavior when max_dois exceeds the number found.

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 first sentence names a specific verb (find, resolve) and resource (DOIs in free text) plus the outcome (clean metadata). It is clearly distinguishable from siblings like get_crossref_work (single work lookup) and cite_dois (bibliography formatting).

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 'When to use' block gives two concrete scenarios (messy reference list/PDF text/URL list, and verifying DOIs from another tool or model) and the closing follow-up explicitly routes to cite_dois. Alternatives and conditions are named, not inferred.

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?

With no annotations, the description carries the full burden and does so richly: Crossref has no exact-phrase search, query matches ANY word so total_results is inflated, offset is capped at 10,000, has_full_text does not imply open access, and cited_by_count only counts Crossref-registered citations. These are exactly the non-obvious behaviors an agent needs.

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-loads purpose, then usage, then the critical matching caveat, then args/returns/examples — a logical, skimmable structure. The Args section is lengthy, but with 20 undocumented parameters that length is largely earned; only minor trimming 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?

Given 20 params, no annotations, and a defined output schema, the description still supplies the return shape, paging limits, abstract-token tradeoff, and interpretation caveats. 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 description coverage is 0% across 20 parameters, so the description must compensate — and it does, documenting every argument with format rules (date formats, offset cap), accepted values (work_type ids, sort keys, order), and worked examples. This is well above the baseline expected when the schema does the work.

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 with scale (~170M scholarly works) and explicitly names the sibling it is not ('use analyze_crossref_topic for phrase-accurate trends'). An agent can distinguish it from get_crossref_work, analyze_crossref_topic, and the author/journal tools 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?

A dedicated 'When to use' block gives three concrete scenarios and routes each alternative (bibliographic, author, orcid, issn) to the right tool. It also names the exact alternative for phrase-accurate trends, so when/when-not is fully covered.

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?

With no annotations provided, the description carries the full burden and delivers: it discloses the OpenAlex dependency, the OPENALEX_API_KEY budget behavior (10x daily budget vs keyless), per-call cost (~4 list calls), automatic matching that is 'occasionally wrong', and the non-obvious fact that open_access.url is a legal free copy while DOI != free PDF.

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 a one-line summary, then cleanly sectioned into When to use / Args / Returns / Notes. It is longer than average but every block (provider rationale, cost, matching caveat) adds distinct value 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?

For a multi-source traversal tool, the description covers provider, cost, caveats, args, and the concrete return shape (seed, backward/forward totals, strong_candidates). Even with an output schema present, the returned-key summary is useful and everything an agent needs to call it correctly is present.

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 0%, so the description must compensate, and it does: 'doi' is defined as the seed paper's DOI and 'rows' is given the semantics 'works per direction, sorted by citation count (1-50, default 10)' — including the range and sort order absent from 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 (citation snowballing) and resource (one seed paper) and enumerates the three traversal directions (backward/forward/related). It also names the underlying provider distinction (OpenAlex for forward citations, since Crossref lacks them), which separates it from siblings like find_related_works and get_crossref_references.

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 'When to use' block gives both a scenario (systematic literature review snowballing from seed papers) and concrete user-style questions it answers. An agent can route to this tool without guessing.

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