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

With no annotations, the description carries the full load and does it well: it discloses the entitlement requirement for Scopus (subscriber key for REF-view), that OpenAlex needs none, and that outputs are written to disk as GraphML plus a CSV edge list. It omits run-time behavior such as cost, rate limits, or what the tool returns to the caller.

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?

Four dense sentences, front-loaded with the operation and edge definition, then the entitlement caveat, then the output artifacts. Every sentence contributes and none is redundant.

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 tool with no output schema and no annotations, the description covers the coupling definition, auth prerequisites, and on-disk outputs, which is most of what an agent needs. It does not clarify the response payload or whether this runs synchronously or as a job.

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 source, seed_ids, and min_shared thoroughly, including the never-mix-sources rule. The description restates the Scopus entitlement constraint but adds no syntax or meaning beyond what the schema provides, warranting 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 and resource ('build a bibliographic-coupling graph for a set of seed papers') and immediately defines the coupling relation and edge weight, which cleanly separates it from siblings like co_citation and citation_network. An agent can identify the operation 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?

'Maps the current research front' hints at the analytic purpose, but the description never states when to prefer this over siblings such as co_citation, citation_network, or research_fronts, nor any when-not condition. Usage is implied rather than prescribed.

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 behavioral burden. It usefully discloses the data provenance (Crossref carrying Retraction Watch) and the breadth of notice types, which the schema does not convey. However, it says nothing about permissions, rate limits, latency (a per-paper Crossref lookup), or whether missing papers are returned as clean rather than unlisted.

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?

Three tight sentences: what it returns, from where, how to feed it, and how it relates to a sibling. The core resource and source are front-loaded with no redundant padding.

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 low-complexity lookup with no output schema and no annotations, the description covers inputs, data source, and notice categories adequately. The main gap is the shape of the result (per-paper flags vs. a notice list), which matters for an agent interpreting the response, but the tool's simplicity keeps this a minor omission.

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 67%, with 'dois' left undocumented in the schema. The description restates the three accepted input forms and adds that corpus_file originates from import_records, which is genuine added meaning. Beyond that it does not clarify precedence when multiple inputs are given, or formatting expectations, so it does not fully compensate for the coverage gap.

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 names the concrete resource (retraction notices: retractions, withdrawals, expressions of concern, corrections) and the scope (a set of papers), plus the upstream source (Crossref / Retraction Watch). It is not phrased as a verb+resource, but an agent can immediately tell this is a retraction-status lookup. It also distinguishes itself from citation_network, which covers the same check.

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 input options ('Give DOIs, Scopus IDs, or a corpus_file from import_records') and clarifies its relationship to citation_network, which already runs the check on every network — implying when this standalone call is redundant. It stops short of an explicit when/when-not statement, so it is strong context rather than full routing 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?

With no annotations, the description carries the full burden and does so well: it enumerates the five statuses (found, contexts_withheld, edge_absent_in_s2, citing_paper_unresolved, cited_paper_unresolved), the fallback chain when S2 lacks sentences, the context_source values, the 50-pair cap, the ID resolution order (DOI, MAG ID, title+year) and the reported route. This is unusually rich behavioral disclosure for a read tool.

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?

Dense but front-loaded: the purpose leads, then intent, then evidence framing, then operational details. Every sentence serves a purpose (statuses, fallback, cleaning/ranking), though the concentration of status and source enumerations makes it somewhat heavy to scan in one pass.

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 tool with no annotations and no output schema, the description fills every gap an agent needs: what is returned (cleaned, ranked sentences with intent and source provenance), the possible result statuses, and the fallback path. Nothing material appears missing for correct invocation.

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, but the description adds real value beyond the schema: it specifies that citing/cited and pairs are alternate forms for single vs multiple edges, names the accepted ID systems, explains the resolution route, and states the 50-pair limit. It does not elaborate on construct_terms or max_contexts semantics beyond the schema wording.

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: 'How one paper cites another' with the specific outputs (citing sentences, citation intent categories, influential flag). This is clearly distinguishable from sibling tools like get_citing_papers (which lists citers) and get_references, since it targets the content and character of a single citation edge.

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 implied use case ('Evidence for whether a citation edge carries the cited idea or is a passing mention'), which frames the decision context. But it never explicitly says when to use this over get_citing_papers, get_references, or fulltext_oa alternatives, nor any exclusions, so usage remains inferential.

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: global deduplication, output written to disk as JSON plus an inline base64 corpus for sandboxed callers, entitlement requirements for scopus, thinner/absent OpenAlex reference lists for AIS eLibrary papers, and explicit quota risk from forward fan-out with max_per_node as the bound. It also warns not to mix sources within one analysis.

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?

Dense and front-loaded: the walk semantics come first, then output shape, then sort/source trade-offs. Slightly overlong, and the trailing 'Server version is included in every response' sentence is marginal, but nearly every sentence carries operational weight.

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 8-parameter tool with no output schema, the description covers return shape (disk JSON, inline summary, base64 corpus), source caveats, and quota behavior. Minor gaps remain around ID handling for backward walks on OpenAlex specifically, but overall it is sufficient to call the 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 description coverage is 100% and the schema already explains sort, scope, source, direction, min_citing and max_per_node in comparable detail, so the description largely restates it. It adds a little interaction context (sort is forward-only, scope filter goes into the search so the cap counts in-scope papers), but the baseline of 3 applies 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 and resource ('Walk the citation lineage of a seed paper across multiple generations') and immediately operationalizes it with forward/backward semantics. An agent can distinguish this from siblings like get_citing_papers or citation_network based on the multi-generation walk framing alone.

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 when-to-use guidance on the sort modes ('citedby' gives a citation backbone vs 'coverDate' can produce a recency-dominated walk) and on source selection (openalex when there is no Scopus entitlement). It does not name sibling alternatives such as get_citing_papers or citation_network, so the routing signal against other lineage tools is left implicit.

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 discharges it: it discloses completeness thresholds (90%, 5 missing), retry-after-rate-limit behavior, provisional main-path marking, duplicate listing, output formats, one cached request per paper, and job-ID escalation. Exceptionally rich behavioral disclosure.

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 method, then caveats, then outputs, then cost. It is long, but the length is justified by 18 parameters and substantial hidden behavior; each sentence 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?

For a very complex tool with no output schema and no annotations, the description covers compute method, completeness semantics, error states, job escalation, output artifacts, and cost — everything an agent needs to call and interpret it.

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 descriptions are themselves highly detailed, so the baseline is 3; the description adds only marginal extra meaning (ID formats by source), largely restating what the schema already documents.

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 — 'Direct-citation network within a set of papers' — and details the three-step mechanics (fetch references, filter to set, run main-path analysis). This is clearly distinguishable from coupling, co-citation, and lineage siblings.

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 operational routing ('give ids ... or a query', 'never mix sources') and the >50-paper job polling path with job_status/job_result, but never states when to prefer this tool over bibliographic_coupling, co_citation, or citation_lineage. Usage context is implied, not contrasted with alternatives.

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 reasonably well: it discloses the quota-bounding role of max_citing_per_seed and that output is persisted to disk as GraphML + CSV rather than returned inline. It omits runtime/job behavior (whether this is an async job like its siblings job_status/job_result imply) and error/retry semantics, which is a notable gap for a network-fetching tool.

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?

Five tightly packed sentences, front-loaded with the core method definition, then the weight/cosine semantics, then the practical bounds and output artifacts. No filler and every sentence carries information an agent needs.

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 tool with no output schema, the description usefully names the returned artifacts (GraphML + CSV edge list on disk) and the source-entitlement split is covered by the schema. It does not clarify whether invocation is blocking or returns a job handle, which matters given the sibling job_status/job_result tools.

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 source, seed_ids, min_shared and max_citing_per_seed in detail. The description's only parameter remark ('max_citing_per_seed bounds the API quota used per seed') largely repeats the schema's own 'Limits quota usage' note, adding little 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?

States a specific verb and resource ('Build a co-citation graph for a set of seed papers') and defines the method precisely (co-cited when a later paper cites both), which implicitly separates it from related graph tools like bibliographic_coupling. However, it never names a sibling or explicitly distinguishes this technique from the adjacent citation_network/citation_lineage tools, so differentiation 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?

The clause 'Maps the intellectual base of a field' implies the analytic context in which this tool is appropriate, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., bibliographic_coupling). Usage is only implied.

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. It discloses that the tool is a read/analysis operation on an existing file and describes its outputs, but it does not state whether the file is modified, whether missing or partial coder columns cause errors, or what happens with fewer than two coders. For an analysis tool with no annotations, this is adequate but incomplete.

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 moderately dense sentences front-load the core action and then list outputs and the alternative use case. The parenthetical caveat about CSV separators is useful but slightly tacked-on; overall efficient 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?

The description covers the input provenance, required format, computed statistics, and secondary validation use, which is more than the schema alone. With no output schema, describing the returned metrics and matrix is necessary and done. It could more fully explain edge cases (e.g., fewer than two coders, missing labels), which keeps it below 5.

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 each parameter's meaning and defaults. The description adds the contextual fact that coder columns come from the two coders and that the reference column is the draft label, but does not add new syntax or format detail beyond the schema. 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?

The description states a specific verb (computes inter-coder agreement) on a specific resource (a coding sheet produced by path_transmission or citation_network). It enumerates the exact outputs (Cohen's kappa with 95% interval, Landis & Koch reading, per-label agreement, confusion matrix, disagreeing edges) and a secondary function (validating draft labels against coders). No sibling tool shares this purpose.

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 a clear precondition: 'once two coders have filled their columns' and points to the tools that produce the input (path_transmission, or citation_network with edge_contexts). It also defines the format the sheet must be in (CSV comma/semicolon/tab, as saved from Excel). It doesn't state when NOT to use this tool, but the prerequisites are explicit.

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 behavioral burden well: it discloses the four check categories and the shape of the result (one-line verdict plus 'unavailable_tools'). It does not explicitly state that the operation is read-only or note any latency/cost, which keeps it short of 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 the purpose, then the checks, then the return shape, then the usage trigger. Three sentences are dense but each carries actionable content; the parenthetical about 'Error translating query' is arguably the most valuable sentence, so placement late is the only minor flaw.

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 zero-parameter diagnostic with no output schema and no annotations, the description still explains what is checked and what the report contains, including the 'unavailable_tools' key. Nothing an agent needs to decide to call it or interpret its result 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?

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. No parameter-level ambiguity exists for an agent to resolve.

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 (diagnose) and resource (Scopus connectivity and entitlement) and enumerates exactly what it checks. It is unmistakably distinguishable from every sibling, all of which are search, analysis, or utility 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?

Explicitly says when to run it ('Run this first when Scopus behaves strangely'), names the concrete trigger ('valid searches fail with Error translating query'), and explains the likely root cause versus a wrong diagnosis (missing subscriber entitlement, not bad syntax).

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 and does well: it discloses the return payload (rank, percentile, quartile, CiteScore, CSV, SRCID fragments), the data vintage ('latest complete CiteScore year'), and the edge-case behavior that ambiguous category names return candidates rather than failing. It omits any auth/quota or result-size expectations, so not 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?

Long but dense and front-loaded: purpose, cut-off semantics, category format, return payload, and data vintage each appear once in a single flowing sentence. Nothing is wasted, though the run-on structure makes it harder to scan than a split sentence would be.

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 no annotations, the description must cover purpose, filtering semantics, inputs, and return values — and it does all four, including downstream usability of the SRCID fragments. An agent can call this correctly without opening the 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 description coverage is 100%, so the baseline is 3. The description reinforces the percentile semantics (Q1 = 75, top 10% = 90) and gives ASJC name/code examples, but these largely duplicate what the schema already documents.

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+scope: listing journals filtered by Scopus subject category and CiteScore percentile. This is clearly distinguishable from siblings like get_journal_metrics (metrics for a known journal) and search_all (which this tool feeds query fragments to).

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?

Frames the use case explicitly ('the quality cut-off for scoping a literature review') and points to search_all as the downstream consumer of the returned SRCID(...) fragments. No explicit when-not-to-use or named alternative for the same job, so not 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 provided, so the description carries the full burden of behavioral disclosure. It states this is a retrieval operation, implying read-only behavior, but doesn't mention any constraints like rate limits, authentication needs, error handling, or what 'full details' entails. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.

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 a single, clear sentence with zero wasted words. It's front-loaded with the core purpose and efficiently conveys the essential information without unnecessary elaboration, making it easy to parse quickly.

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 no annotations, no output schema, and a single parameter with good schema coverage, the description is incomplete. It doesn't explain what 'full details' includes in the response, potential errors, or usage constraints. For a retrieval tool, this lack of output and behavioral context is a significant shortfall.

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%, with the single parameter 'scopus_id' well-documented in the schema. The description adds minimal value beyond implying this is the primary identifier, but doesn't provide additional context like format examples or validation rules. 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?

The description clearly states the action ('Retrieve full details') and resource ('for a specific document by Scopus ID'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this from sibling tools like 'get_author_profile' or 'get_citing_papers' beyond the document focus, which prevents a perfect score.

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 description provides no guidance on when to use this tool versus alternatives like 'search_scopus' or other siblings. It mentions retrieving details for a 'specific document,' implying you need a known Scopus ID, but doesn't state this explicitly or provide any context about prerequisites or alternatives.

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 of behavioral disclosure. It states it's a retrieval operation, implying read-only behavior, but doesn't disclose any traits like rate limits, authentication needs, error handling, or what the profile includes (e.g., fields returned). This leaves significant gaps for a tool with no annotation coverage.

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 a single, efficient sentence with zero waste. It's front-loaded with the core purpose ('Retrieve an author's profile'), and every word earns its place by specifying the key constraint ('by Author ID'). No unnecessary details or 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?

Given the tool's simplicity (1 parameter, 100% schema coverage) but lack of annotations and output schema, the description is incomplete. It doesn't explain what an 'author's profile' entails (e.g., fields like name, affiliation), potential errors, or return format. For a retrieval tool with no structured output, more context is needed.

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 description adds minimal meaning beyond the input schema, which has 100% coverage and clearly documents the single parameter 'author_id' as 'The Scopus Author ID'. The description reiterates 'by Author ID' but doesn't provide additional context like format examples or validation rules. Baseline 3 is appropriate as 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?

The description clearly states the action ('Retrieve') and resource ('author's profile'), specifying it's by 'Author ID'. It distinguishes from siblings like 'get_citing_papers' or 'search_scopus' by focusing on profile retrieval rather than citations or searches. However, it doesn't explicitly differentiate from all siblings (e.g., 'get_abstract_details' might also retrieve data by ID), keeping it from a perfect score.

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 description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid Author ID), exclusions, or comparisons to sibling tools like 'search_scopus' for finding authors by name. Usage is implied by the action but lacks explicit context.

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 discloses the two output channels (file plus inline), that entries derive from publisher metadata via DOI content negotiation, that errors are included in the output so author names should be verified, that DOI-less papers get a minimal entry marked with a note, and the 200-identifier cap.

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 is front-loaded in the first clause, and each subsequent sentence adds a distinct operational fact (identifier types, metadata source, fallback, limit) 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?

There is no output schema, so the description must explain what comes back; it covers both the .bib file and the inline return, the error-inclusion behavior, and the fallback entry format, leaving nothing material unstated for a one-parameter 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 description coverage is 100% and there is only one parameter, so the schema already documents the identifiers field. The description repeats the accepted formats without adding new syntax or constraints beyond the schema, so the 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?

States a specific verb and resource: producing BibTeX entries for a list of papers, written to a .bib file and returned inline. This is clearly distinguishable from siblings like resolve_identifier or search_scopus, which do not emit BibTeX.

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 the accepted identifier types (DOIs, Scopus IDs/EIDs, OpenAlex work IDs) and the fallback path for items without DOIs, which tells the agent when this tool is appropriate. It does not, however, explicitly name alternative tools or state when not to use it.

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 discloses almost nothing behavioral. It implies a read-only retrieval but says nothing about entitlement/rate-limit implications, pagination, result size limits, or ordering behavior (all of which only surface in the schema's parameter 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?

A single front-loaded sentence with no wasted words; the key concept (forward citations) is immediately clear. It is efficient, though arguably under-specified rather than maximally informative.

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, so the description should describe the return shape (what fields a citing paper carries, how many, pagination) but only says 'a list of papers'. Given the source-dependent result IDs (Scopus vs OpenAlex) noted in the schema, this leaves an agent guessing about the response.

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%, and the schema itself thoroughly documents sort, count, source and scopus_id (including cross-source ID behavior and entitlements), so the baseline of 3 applies. The description adds no parameter-level meaning beyond the parenthetical about which citations are returned.

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 (Retrieve) and resource (papers that have cited the specified document), and the parenthetical '(Forward Citations)' disambiguates it from a backward-citation tool like get_references. It does not, however, explicitly name or contrast itself with the many citation-oriented siblings (citation_network, citation_lineage, resolve_citers).

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?

There is no when-to-use guidance: it never says when to prefer this over get_references, citation_network, citation_lineage, or resolve_citers, nor any precondition beyond what the schema states. The scope is implied by the verb, but no alternatives or exclusions are offered.

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 full burden and does so richly: it discloses the provider waterfall, version naming, provenance, that full body is written to disk (never returned inline), and includes a ToS note about non-commercial use and redistribution restrictions. This is exceptional 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?

Front-loads the purpose and waterfall, then returns and ToS note. It's dense but every sentence adds value. Slightly long but appropriate given the complexity.

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, so description must explain returns – it does (provenance, character count, file path, sample) and notes the full body is on disk. Complete for a complex retrieval tool, though it could specify error handling or rate limits.

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 includes descriptions for both parameters, so the baseline is 3. The description mentions the waterfall tiers but doesn't add syntax or constraints beyond what the schema already documents.

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+resource: 'Retrieve the full text of a paper' and it names the retrieval mechanism (provider waterfall). Clearly distinguishes itself from search_fulltext (which likely searches within text) and get_abstract_details (abstract only).

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 the waterfall tiers and the 'prefer' parameter for skipping tiers, which implies when to use. However, it doesn't explicitly state when to prefer this over get_abstract_details or search_fulltext, though the full-text vs abstract distinction is implied.

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 discloses entitlement requirements per source, the 200-journal cap, that SRCIDs cost one Scopus search each, that unfound journals are listed and never dropped, and that results are also written to CSV. These are exactly the operational traits an agent needs and none are derivable from the schema.

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?

Dense and front-loaded, leading with what the tool returns before covering sources and limits. Every clause carries information, though the opening sentence stacks several metrics and provenance details, making it slightly heavy to parse.

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 3-param read tool with no output schema and no annotations, the description covers inputs, entitlements, limits, edge-case handling (missing journals), and output side effects (CSV). 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 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains that SRCIDs are mapped to ISSNs via one Scopus search each, that OpenAlex accepts only ISSNs, and that Scopus source_ids are Scopus-only. The ISSN hyphen tolerance is left to the schema, which already documents it.

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 ('journal metrics for a list of journals') and immediately scopes the two data-source variants (Scopus vs OpenAlex). It is clearly distinguishable from siblings like find_journals or search_scopus, since the agent knows this retrieves metrics for already-identified 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?

Gives concrete input guidance (ISSNs or SRCIDs) and names the alternative source path with its condition ('source=openalex ... no entitlement' vs Scopus needing search entitlement). It stops short of explicitly stating when NOT to use this tool or which sibling to prefer for adjacent tasks, so it is clear context rather than full when/when-not routing.

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. It discloses key behavioral traits: it's a read operation (implied by 'Get'), and it specifies that quota values are updated only after making a request, which is crucial for understanding its timing and accuracy. It does not cover other aspects like error handling or rate limits, but the added context is valuable given the lack of 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?

The description is two sentences, front-loaded with the core purpose and followed by an important behavioral note. Every sentence earns its place by providing essential information without waste, making it highly efficient and well-structured.

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 low complexity (0 parameters, no output schema, no annotations), the description is complete enough for a simple quota-checking tool. It explains what the tool does and a key behavioral constraint. However, without an output schema, it could benefit from specifying the return format (e.g., numeric values or a structured object), but the current description is adequate for the context.

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?

There are 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description adds no parameter-specific information, which is appropriate. A baseline of 4 is applied for zero parameters, as it avoids unnecessary details and focuses on the tool's purpose.

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 clearly states the specific action ('Get') and resource ('current API quota status') with precise details about what information is returned ('remaining/limit'). It distinguishes itself from sibling tools (which focus on academic data like papers, authors, and citations) by addressing API quota monitoring.

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 description provides clear context on when to use this tool: to check API quota status, with a note that values update only after making a request. This implies usage after API calls to monitor limits. However, it does not explicitly state when not to use it or name alternatives, though siblings are unrelated (e.g., no alternative quota-checking tool exists).

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 were provided, so the description carries the full burden, and it does disclose the key behavioral constraint: Scopus requires an entitled subscriber key while source='openalex' does not. It also confirms read-style retrieval semantics implicitly and points to the reply's completeness reporting, though it stops short of describing truncation or error behavior.

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?

Three short sentences with zero padding; purpose and the sibling contrast are front-loaded before the less critical entitlement note. Every clause 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?

For a 5-parameter retrieval tool with no output schema, the description covers purpose, directional alternative and auth prerequisites, and the schema fully documents each parameter. The absence of any statement about what the returned reference records contain is the only real 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 description coverage is 100%, so count, source, scopus_id, filter_ids and check_completeness are already documented with defaults, enums and behavior. The description adds only the entitlement point already implied by the source enum's schema text, so the baseline 3 is appropriate.

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 ('Retrieve the cited-reference list of a document'), gives the domain synonym (Backward Citations), and names the mechanism (Abstract Retrieval REF view). It explicitly distinguishes itself from the sibling get_citing_papers by direction of citation, so an agent can route 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?

Explicitly frames the choice against get_citing_papers ('Complements ... which returns forward citations'), which is exactly the disambiguation an agent needs for citation tools. It also flags the entitlement prerequisite for source='scopus'. No explicit when-not conditions beyond that, so a 4 rather than 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?

With no annotations, the description must carry the full burden. It discloses what is returned (version and health summary) but does not explicitly state that the operation is read-only, side-effect-free, or what the health summary entails. For a zero-parameter tool the risk is low, but the disclosure is minimal.

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, front-loaded with the return values and followed by a usage cue. Every sentence earns its place with no 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 zero-parameter, read-only server info tool with no output schema, the description tells the agent what it returns and when to call it. It could be slightly more specific about the health summary contents, but it is largely complete.

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 no parameters, so the baseline is 4. The description adds no parameter information because there is none to add, which is appropriate.

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 ('Return') and resource ('server version and a health summary'), making the tool's purpose clear. It does not explicitly distinguish itself from sibling diagnostic tools like diagnose_connection or get_quota_status, but the resource is distinct enough.

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 provides a clear when-to-use: 'Call this to confirm which build you are talking to.' No when-not-to-use or named alternatives are given, but the context is sufficient for a simple info tool.

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 it does disclose meaningful side effects: it writes a PNG and a Pajek file, and returns a list of papers with local and global citation counts. However, it omits where files are written, whether the operation is long-running, and any entitlement/permission implications beyond what the schema says about source.

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?

Three sentences, front-loaded with the core definition of the visualization before moving to inputs and outputs. Dense but each sentence carries information; 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 7-parameter tool with no output schema and no annotations, the description adequately covers what the tool computes and what it produces (files plus a paper list with citation counts). It is missing only operational details such as runtime and output file location, which keeps it short of a 5.

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 ids, query, top, scope, source, corpus_file and max_results thoroughly. The description only adds 'Give ids or a query', which restates the schema's own 'Use this or query' guidance, so the baseline of 3 is appropriate.

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 names a specific artifact (Garfield's historiograph) and defines it precisely: most-cited papers within the set on a time axis, with intra-set citations and the global main path highlighted. It implicitly distinguishes itself from the sibling path_transmission/main-path tools by positioning itself as the complementary picture, though it never names a sibling explicitly.

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 input guidance ('Give ids or a query') and a soft positioning cue ('Complements the main path with the picture readers expect beside it'), but offers no explicit when-to-use/when-not-to-use rule versus citation_lineage, path_transmission, or bibliographic_coupling. Usage 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses merge keys (Scopus ID, WoS ID, DOI, title+year), the resolution fallback order (DOI, then exact title+year), and that thematic_evolution re-reads keywords from the file with no API calls. It omits where the corpus file is written, permission/API-key needs for Scopus lookups, and error behavior for unparseable files.

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?

Single dense paragraph, but tightly front-loaded with the core action and format list before the deduplication and resolution details. Every sentence carries information, though the downstream-tool sentence is long and could be trimmed slightly.

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, yet the description states the return values (corpus file path and Scopus IDs) and explains the durable reuse of the produced file. For a two-parameter import tool this covers everything an agent needs to invoke and chain 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 coverage is 100% (baseline 3), and the description adds real meaning beyond it: it explains that resolve performs Scopus ID lookups for records lacking one and the matching order used, which the schema's one-line description does not 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?

States a specific verb (read/import) and resource (saved bibliographic exports) and enumerates the supported formats (Scopus CSV, RIS, BibTeX, WoS plain-text/tab-delimited) with format auto-detection. An agent can immediately tell this is the file-ingestion entry point, distinct from the search_* and analysis siblings.

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?

Clearly scopes when to use it (importing locally saved exports) and what to do next, naming the downstream tools (citation_network, rpys, historiograph, research_fronts, thematic_evolution) and the corpus_file handoff, plus the default-true resolve behavior. The workflow context is explicit rather than implied.

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. It usefully discloses entity resolution rules (DOI first, else title+year) and that the Scopus side is unverified and that coverage becomes a reported property. It omits permissions, rate/API behavior across three external indices, and what the result looks like (counts, overlap matrix), leaving its behavioral profile incomplete.

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?

It is compact and front-loads the core operation, the match rule, and the caveat in four short sentences with no redundancy or filler instructions. The sentence 'Makes index coverage a reported property of a study rather than a hidden one' is the one line that leans toward motivation rather than specification.

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-index tool with no annotations and no output schema, the description covers the operation, the matching rule, and one caveat, so an agent can call it correctly. It still leaves open the shape of the return (per-index citation sets, overlap counts) and any permission or index-access prerequisites, so it is adequate rather than complete.

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 scope (ISSN list or basket name), seed_ids, and max_results. The description adds only indirect meaning ('under the same journal scope', the DOI/title+year matching), which is about results rather than parameter semantics, so the baseline 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 concrete operation: computing, across Scopus, OpenAlex, and Semantic Scholar, which papers cite the seeds and how the three sets overlap. The resource (cross-index citing papers) and scope restriction (same journal scope) are clear, and it names a sibling (resolve_citers), so an agent can distinguish it. The question-style opening is slightly indirect versus a direct verb+resource statement.

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 one routing hint ('Scopus side: REF() search (not verified; use resolve_citers for that)'), which tells the agent when to prefer resolve_citers. However, it never says when to choose this tool over get_citing_papers, citation_network, or search_all, and no explicit when-not guidance is offered beyond the REF caveat.

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 does disclose one useful behavior — that a still-running job yields a status instead of output — but says nothing about unknown/expired job_ids, error behavior, whether the call blocks, or the size/shape of the returned output.

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?

A single short sentence with no filler, and the core concept (finished job output) is front-loaded. The parenthetical caveat is terse and earns its place, though the sentence would be stronger as an actionable statement.

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 tool with no annotations, no output schema, and an undocumented parameter, the description does too little. It should at minimum explain that output is fetched by job_id and describe what is returned for a completed job versus a running one.

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?

There is one required parameter, job_id, with 0% schema description coverage, and the description never mentions it. An agent must infer that job_id is the identifier of the job whose result it wants, and gets no hint about its format or whether it comes from a prior submission call.

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 names the resource (a finished background job's output) and adds a scope note for running jobs, so the agent can guess the intent. But it is phrased as a noun phrase describing a return value rather than a retrieval action, and it never mentions job_id or contrasts with its obvious sibling job_status.

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 implies usage after a job completes, but gives no explicit when-to-use guidance and never names job_status as the alternative for checking progress. With a sibling tool that is nearly identical in name and function, some routing guidance was expected.

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. It usefully discloses the three terminal/transient states and that a 'last step' is returned, but says nothing about polling cadence, whether a finished job's payload is retrievable here, or retention/expiry of jobs.

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?

One sentence, front-loaded with the resource and the returned states; the parenthetical example list is the only slightly expendable content. No filler or restatement of the name.

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-parameter status tool with no output schema and no annotations, the description covers the essentials of what is returned. It remains incomplete on the lifecycle question — how to move from status to actual results, and how long a job_id stays valid.

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 job_id parameter, so the schema gives no meaning at all. The description compensates partially by explaining that job_id originates from a long tool call that passed the sync budget, but it does not describe the id's format or where to source it explicitly.

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?

Names a specific resource (a background job) and its verb (report state), and enumerates the possible states plus the last-step detail. It is clear what comes back, though it never contrasts itself with the sibling job_result, which covers the result-fetching counterpart.

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 description explains the trigger context well — jobs spawned by long tool calls that exceeded the sync budget — so an agent knows when a job_id exists. It stops short of stating when to prefer this over job_result or what to do after seeing 'finished', leaving the routing inference to the agent.

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 burden well: it discloses the data sources (Semantic Scholar then citing paper full text), the SPC weight fallback via corpus_json, and that the tool writes a CSV coding sheet. It also honestly frames draft labels as heuristics rather than findings, though it omits where the CSV lands and any rate/error behavior.

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 pipeline before the label taxonomy, and every clause carries information. The label definitions are necessarily verbose but arguably earn their place; it remains one dense paragraph with no restated boilerplate.

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 complex, non-annotated tool with no output schema, the description covers the process, the derived labels, and the returned artifact (CSV coding sheet with blank coder columns). Remaining gaps — output location and failure/fallback detail — are minor.

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 3; the description goes further by tying parameters to output behavior — corpus_json supplies each edge's SPC weight, max_contexts bounds contexts kept per edge, and construct_terms drives the context-naming count used in labeling.

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 ('Transmission audit of a main path') and enumerates exactly what is gathered per consecutive edge. It is clearly distinguishable from siblings like citation_context (single citation) or citation_network (path construction, whose output it consumes).

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 context is clear from the pipeline description (it operates on a main path as citation_network reports it, and produces a coding sheet for two coders). It implies when this is appropriate but never explicitly excludes alternatives such as citation_context or coding_agreement.

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 per-source request behavior (Scopus issues one request per year, OpenAlex one request for all years), the 60-year cap, and the cross-source counting caveat, which materially affects result interpretation. It stops short of describing the returned structure or error/partial-result behavior.

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?

Three tightly packed sentences, front-loaded with purpose before the per-source mechanics and the comparability warning. Every clause conveys operational information; nothing is decorative or repeated from 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 4-parameter tool with no output schema, it covers source selection, syntax, year-range constraints, and interpretation caveats adequately, and the stated purpose implies a per-year count series return. It could be slightly more explicit about the exact shape of the returned counts, but the gap is minor.

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 real semantic value beyond the schema: it explains the query syntax difference per source (Scopus syntax vs plain words quoted against title/abstract) and that from_year/to_year are required for Scopus and capped at 60 years, which the schema does not 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?

States a specific verb and resource ('Count publications per year for a query') and immediately contrasts with the record-returning search siblings by framing the output as a per-year count for charting trends. An agent can tell this apart from search_scopus/search_all 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 a concrete when-to-use scenario ('to chart how attention to a topic rose and fell') and prescribes comparing trends within a source rather than levels across sources. It does not name an explicit alternative tool or state when not to use this one, which keeps it 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?

With no annotations, the description carries the full burden and does well: it discloses side effects (writes JSON, Pajek .net and .clu partition files) and a cost model (one reference and one abstract request per paper, cached). It omits failure modes, permissions specifics beyond the schema, and runtime/large-set caveats.

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?

A dense but well front-loaded paragraph: the core operation leads, interpretation and cost follow. Every sentence carries information, though the main-path elaboration is lengthy relative to its decision value for an agent.

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 8-parameter, no-output-schema tool, the description usefully summarizes the returns (fronts described by years, density, core papers, distinguishing keywords; per-paper front membership; output files). What an agent needs to invoke it correctly is largely covered, though scope/source interaction is left to the 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 description coverage is 100%, so the schema already documents ids, query, scope, source, min_size, resolution, corpus_file and max_results. The description adds only broad framing ('Give ids or a query') and no extra syntax, defaults, or interactions beyond what the schema provides, so baseline 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?

States a specific verb and resource: computing Louvain communities of a paper set's direct-citation network, plus main-path front membership. This is clearly distinguishable from siblings like citation_network, thematic_evolution and path_transmission 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?

Gives concrete input options ('Give ids or a query') and explains the analytical interpretation (a path staying in one front vs hopping). However, it never states when to prefer this over adjacent tools such as citation_network or path_transmission, so the routing guidance stops short of explicit alternatives.

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 discloses the REF()/merge/verify pipeline, the per-strategy table contents, that cross_check consults OpenAlex and Semantic Scholar while 'the Scopus result stays Scopus-only', and that long runs may return a job ID requiring polling. This is behavior beyond what any structured field provides.

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?

Three dense sentences, front-loaded with purpose and workflow before the cross-check and job-ID caveats. Efficient, though the middle sentence is information-heavy and could be split for readability.

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 complex multi-strategy tool with no output schema and no annotations, the description covers the return shape (per-strategy table, counts, misses) and the async job path adequately. Minor gaps remain around error/entitlement failure behavior, but an agent has enough to call 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 8 parameters, including scope's ISSN rationale, inline modes, source entitlements, and cross_check defaults. The description largely restates this (e.g. cross_check default, queries examples) rather than adding new semantic detail, so baseline 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?

States a precise verb+resource ('all papers citing one or more seed papers') and immediately scopes it with the mechanism ('several search strategies at once and verified'). The multi-strategy + verification framing implicitly distinguishes it from the simpler sibling get_citing_papers.

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 description explains the internal workflow but never states when to pick this over siblings like get_citing_papers or search_scopus. It does give operational guidance for long runs ('poll job_status, then job_result') and notes cross_check defaults on when scope is set, but no explicit when/when-not or alternative routing.

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. It does disclose the return payload (scopus_id, eid, doi, pii, title), which is real value with no output schema, but says nothing about failure modes for unknown/ambiguous identifiers, permission requirements, or rate limits.

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 sentences, tightly front-loaded: capability first, usage second. No boilerplate or repetition of the name.

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 simple two-parameter lookup with no output schema, the description adequately covers what is returned and why to use it. It only lacks detail on error/ambiguous-ID behavior, which is a minor gap for this complexity level.

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 both parameters are already documented in the schema (baseline 3). The description adds only marginal value by implying any of the four ID types is accepted and auto-detected, without explaining the id_type override behavior.

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 (Resolve) on a specific resource (any document identifier), enumerates the accepted ID types (Scopus ID, EID, DOI, PII), and spells out the returned cross-reference set. This clearly separates it from sibling search/retrieval 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?

Gives concrete use cases: obtain a DOI for cross-linking with OpenAlex/Crossref, or normalize an ID before calling other tools. It clearly places the tool as a pre-step utility, though it does not state when NOT to use it (e.g. when the ID type is already known and other tools accept it directly).

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 side effects (writes a CSV and PNG), the cost model (one reference request per paper), caching behavior, cache sharing with citation_network, and OpenAlex batching of 50. It omits permission/error behavior, but the resource and mutation profile is unusually well covered.

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?

It is a single dense paragraph, but it is front-loaded with the method and purpose before cost/side-effect details, and every sentence carries information. Slightly run-on, but 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 9-parameter analytical tool with no output schema and no annotations, the description covers method, inputs, outputs (CSV/PNG), cost, and source handling adequately. It could say more about failure modes or what the returned job/report object contains, but nothing essential to calling 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 baseline is 3; the description still adds value by clarifying what ids should be (a set of papers, e.g. confirmed citers) and by noting the OpenAlex batch-of-50 fetch behavior tied to source. Most other parameter meaning is already 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?

The description names a specific technique (Reference Publication Year Spectroscopy), states the exact algorithm (count cited references by year, subtract five-year median, report peak years with top cited works), and frames the output as the set's historical roots. This is clearly distinguishable from siblings like citation_lineage or bibliographic_coupling.

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 tells the agent what to feed it (ids, a query, or a corpus) and gives a concrete sourcing example ('the confirmed citers from resolve_citers'). However, it never explicitly states when to prefer rpys over alternatives such as historiograph or citation_network, so routing is left partly 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?

With no annotations, the description carries the full burden and does well: it discloses page sizes (25 Scopus, cursor paging past 5,000, 200 OpenAlex), the 50-record threshold above which results are written to disk as JSON/CSV, the entitled-subscriber requirement for Scopus, and quota cost. It omits error/truncation behavior and what happens when max_results exceeds available pages.

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?

Four sentences, front-loaded with the core action and scope, then pagination internals, then the quota caveat. Dense with numbers but each sentence earns its place; no marketing 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 6-parameter search tool with 100% schema coverage and no output schema, the description covers the non-obvious operational facts an agent needs: paging limits, disk-write threshold, inline fallbacks, and quota risk. Only edge-case behavior (errors, empty results) is left unexplained.

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 six parameters. The description reinforces max_results with a quota caveat and source with a 'never mix sources' rule, but adds no syntax or format detail beyond what the schema provides, so the baseline 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?

States a specific verb and resource ('Search Scopus ... or OpenAlex') plus the distinguishing behavior ('page through results automatically, returning up to max_results entries in one call'). It never names the sibling search_scopus, so the agent must infer why this differs from a plain single-source search.

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 real selection guidance: use source='openalex' when no subscriber entitlement exists, use inline modes when the caller cannot read server files, and a caution to use large max_results conservatively due to quota. It stops short of naming alternatives like search_scopus or stating when-not-to-use this tool.

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 behavioral burden. It does disclose the entitlement requirement for Scopus, the fields returned per source, and that results are 'ranked by document count' — useful context beyond the schema. It says nothing about result limits, pagination, or failure modes when entitlement is absent.

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 per-source detail and a closing practical caveat. Dense but each sentence contributes; the only mild bloat is repeating source behavior that the schema already carries.

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 four-parameter, no-annotation, no-output-schema search tool, the description covers purpose, source tradeoffs, entitlement constraints, and result shape well enough to invoke correctly. Minor gaps remain around limits and entitlement-failure behavior, but nothing essential 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 the schema already documents all four parameters including source semantics and name format. The description's per-source result summaries add some meaning (ranked by document count, name variants) but largely restate what the source enum description already says, so the 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?

States a specific verb and resource ('Find authors by name') and immediately scopes it with 'optionally narrowed by affiliation.' It also distinguishes itself from search-type siblings by describing exactly what each data source yields, so an agent can tell it apart from search_scopus or search_all.

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 practical selection guidance: default is Scopus but requires subscriber entitlement, OpenAlex requires none, and 'Common surnames need an affiliation or given name to be useful.' It does not, however, explicitly route the agent to a sibling alternative when this tool is the wrong choice.

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 the auth/access requirement, the publisher-scope restriction, the result cap (1000), the side effect that over 50 results are written to JSON and CSV, and the resource-intensive meaning of context=true (one full-text request per analyzed article). This is unusually rich disclosure for an unannotated tool.

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 the not-titles/abstracts distinction, then the access prerequisite, then the context behavior. Sentences are dense but each conveys a distinct fact; the context=true explanation is slightly verbose but justified by the tool's complexity.

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 9-parameter search tool with no annotations and no output schema, the description compensates well by stating the result cap and the JSON/CSV output behavior for large result sets, and by explaining what context=true returns. Remaining gaps are the undocumented filters (open_access_only, sort semantics), but the core calling contract is complete.

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 78%, so the schema already documents most parameters, and the description largely restates the query-syntax guidance rather than adding new meaning. It does clarify context=true's purpose ('retrieve top results' full texts to count mentions') and the 1000-result cap, but leaves sort, journal, year filters and open_access_only (which has no schema description) unaddressed.

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 the full text of Elsevier/ScienceDirect journal articles) and immediately scopes it against the obvious alternatives by saying 'not just titles and abstracts'. An agent can distinguish this from search_scopus and get_fulltext 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 a clear use case – finding papers that use a construct in their body without naming it up front – plus prerequisites (subscriber access) and coverage limits (Elsevier only). It does not explicitly name a sibling to use instead when those conditions fail, 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?

With no annotations provided, the description carries full burden but only states the basic action without disclosing behavioral traits like authentication requirements, rate limits, pagination, or error handling. It lacks critical context for a search operation in an academic database.

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 a single, efficient sentence with zero waste, front-loading the core purpose. It's appropriately sized for a simple tool, making it easy to parse quickly.

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 complexity of a search tool with no annotations and no output schema, the description is incomplete. It doesn't cover return values, error cases, or operational constraints, leaving significant gaps for an AI agent to understand full behavior.

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 description adds no parameter-specific information beyond what the schema provides (schema coverage is 100%). It mentions 'using a query string' which aligns with the 'query' parameter but doesn't elaborate on semantics. Baseline 3 is appropriate as the schema handles documentation adequately.

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 clearly states the action ('Search for documents') and resource ('in Scopus'), specifying the tool's purpose. However, it doesn't differentiate from sibling tools like 'get_citing_papers' or 'get_abstract_details' which might also involve document retrieval, making it clear but not sibling-distinctive.

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 description provides no guidance on when to use this tool versus alternatives like 'get_citing_papers' or 'get_abstract_details', nor does it mention prerequisites such as authentication or quota limits. It's a basic statement without usage context.

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 outputs written (JSON, CSV, a strategic-diagram PNG), and a cost/rate note ('one abstract request per paper (cached)'). It also flags entitlement requirements for source='scopus'. It stops short of describing failure modes or how caching resolves, but the key operational traits are 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?

Purpose is front-loaded and the paragraph is information-dense, with each clause covering a distinct facet (mechanism, transition types, construct mode, inputs, outputs, cost). It is long, but almost every sentence earns its place; minor compression is 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 11-parameter analysis tool with no annotations and no output schema, the description covers inputs, the produced artifacts, data-source entitlement, and cost, which is close to sufficient. Authentication details and period-selection edge cases remain implicit.

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, but the description adds genuine meaning: how construct_terms behaves ('the theme that holds it, where that theme sits, and the keywords it keeps company with'), why ISSNs are used over journal names, and the prohibition on mixing sources within one analysis. That is value beyond the schema text.

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 scope: themes of a corpus and their change over time, decomposed into per-period co-occurrence clusters on the strategic diagram (Callon centrality/density) and between-period transitions via the inclusion index. This is clearly distinguishable from siblings like topic_landscape or research_fronts, and the construct_terms variant is spelled out.

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 the input alternatives ('Give ids or a query') and when to use construct_terms ('follows a construct through the periods'). It gives context for the terms enum ('for corpora with few keywords'), but never explicitly names a sibling alternative or states when-not to use this tool, so a 5 is not warranted.

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 discloses sampling behaviour (max_papers up to 2000, most recent by default), that coverage is stated, that proceedings/book series are counted separately by default, that the same paper can count in multiple categories, and that Scopus search entitlement is required. These are non-obvious operational traits an agent must know.

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 two core outputs are front-loaded before the counting rules and sampling caveats. It is a dense paragraph with minor verbosity in the venue-type caveat, but essentially every sentence carries decision-relevant 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?

With no output schema, the description must explain what comes back, and it does: papers per subject area plus per-category Q1–Q4 counts, main journals, separate proceedings/book reporting, and the venue-type mix. 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 100%, so a baseline of 3 applies, but the description adds genuine semantics: the rationale for 'sample' (most cited to see where influential work appears), the quartile-counting meaning of journals_only, and the max_papers cap of 2000. It reinforces rather than merely repeats 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 first sentence names the exact output of interest ('where and at what prestige a topic is published') and the second specifies the two reports produced. This is a specific verb+resource definition that clearly separates it from generic siblings like search_scopus or publication_counts.

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 description conveys a clear context (analysing a topic's venue/prestige distribution via a Scopus query) but never states when to choose it over alternatives such as publication_counts or get_journal_metrics, nor any exclusions. Usage is implied by the described output rather than stated as guidance.

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