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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds useful behavioral detail by specifying the returned elements (paths, edge directions, papers) and the external Inciteful backing, going beyond what annotations signal without contradicting them.

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 with the core action front-loaded and the return values in the second sentence. There is no repetition or 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 simple read-only tool with no output schema, the description adequately covers the input relationship and high-level return format. It does not explain max_paths behavior or path/edge-detail semantics, but the schema and annotations cover the remaining essentials, so the gaps 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?

The description adds no meaning beyond the input schema: from/to are already documented as DOI/OpenAlex/PMID/identifiers, and max_paths is neither described in the schema nor the tool description. With 67% schema coverage, the description leaves the max_paths parameter semantically 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?

The description states a specific action ('find citation paths'), the resource ('between two papers'), the source ('using Inciteful'), and the return contents. This clearly distinguishes it from sibling tools like similar_papers or get_paper.

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 use case is implied—when you have two papers and want citation paths—but there is no explicit statement of when to choose this over similar_papers or discover_papers, nor any exclusions or prerequisites. An agent must infer the fitting scenario from the purpose alone.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by stating that the seed is excluded and that similarity is a graph metric, not a quality assessment, which provides behavioral nuance beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundant phrasing. Key information (ranking function, criteria, seed exclusion) is front-loaded, and the caveat about similarity is concise. Every 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 tool with three parameters, no output schema, and rich annotations, the description covers the core purpose, ranking options, and an important caveat. It omits details about the limit parameter and return format, but the absence of an output schema reduces the need to describe returns. Overall, it is adequate for an agent to call 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 only 33% (only the id parameter is described). The description explains the ranking enum (similarity, influence, recent) but does not mention the limit parameter or its constraints. It partially compensates for low schema coverage but leaves the limit parameter undocumented in both schema and description.

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 it ranks papers in an Inciteful graph around a seed paper, specifying ranking criteria (similarity, PageRank influence, publication year) and explicitly notes the seed is excluded. It also clarifies that similarity is a graph metric, not a quality assessment, which distinguishes its purpose from generic search or 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?

The description implies a use case (ranking papers around a seed) but does not explicitly state when to choose this over sibling tools like similar_papers or search_papers. No exclusion criteria or alternative routing is provided, leaving the agent to infer 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the fallback order from OpenAlex to PubMed/PMC BioC, and the return content of source attribution and candidate full-text links.

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 carry the essential information: what is retrieved, from where, fallback behavior, and what is returned. There is no filler or repetition of schema/annotation content.

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, read-only tool with a well-documented schema and no output schema, the description is complete. It explains the purpose, fallback sources, and return value shape, giving an agent enough context to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the id parameter description fully documents the accepted identifier formats including DOI, OpenAlex work ID, PMID, Inciteful ID, PMC12345, and PMC article URLs. The description adds no additional parameter semantics, 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 states a specific verb ('Retrieve'), a specific resource ('a readable abstract'), and names the primary and fallback sources (OpenAlex, PubMed/PMC BioC). It also distinguishes this tool from the full-text siblings by explicitly returning source attribution and candidate full-text links rather than the full text itself.

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 purpose is clear: use this when you need a readable abstract with source attribution and candidate full-text links. It provides clear context for selection, though it does not explicitly mention when to prefer a sibling tool such as get_full_text or get_paper.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail beyond that: it returns chunks with next_offset and content hash, may incur archive download charges, falls back to candidate URLs on failure, and refuses to scrape arbitrary publisher sites. This gives the agent a realistic model of tool 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?

Four sentences, each earning its place: primary behavior, return format, failure fallback, and an explicit exclusion. The most important information is front-loaded, and there is no redundant restating of the tool name or schema fields.

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 multiple sources, conditional API key, failure behavior, and absence of an output schema, the description is fairly complete. It covers the key behaviors needed to use the tool correctly)Skip: it does not fully document all parameter semantics, especially max_chars and offset, and it does not specify the shape of the returned chunks or candidate URLs. Still, this is a minor gap given annotations already cover the safety profile.

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 only 25%, so the description needs to compensate for the three undocumented parameters. It partially does—'from PMC BioC, or OpenAlex structured XML' maps to the source enum, and 'Returns chunks with next_offset' hints at pagination semantics. But offset, max_chars, and the precise way to configure the OpenAlex API key are not explained in the description.

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 operation ('Fetch readable article text'), identifies two distinct sources (PMC BioC and OpenAlex structured XML), and sets boundaries by saying what it does not do ('Does not scrape arbitrary publisher sites'). It is distinct from siblings like get_abstract and get_full_text_links, which are about abstracts and links respectively.

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 gives practical context: it mentions the API-key condition for OpenAlex, charges, and the fallback to web/PDF tools when retrieval fails. However, it never names sibling tools such as get_full_text_links or get_abstract, nor does it explicitly state when to choose this tool over those alternatives. Usage guidance is implied rather than 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context: ordering by best open-access copy, inclusion of license/version/access metadata and archive URLs, and the non-guarantee of availability. No contradiction with 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?

Three sentences, each conveying essential information: what is returned, how results are ordered, and how the agent should use the output. No filler 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?

The description covers the return content (URLs, metadata, archive links), ordering, and caveats. Since there is no output schema, this is sufficient for a simple one-parameter tool. Minor omissions like pagination or result limits are not critical given the tool's scope.

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 `id` parameter is already well-described in the schema with accepted identifier formats. The description does not add further parameter-level meaning, 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?

The description states a specific verb and resource: 'Return potential full-text PDF and article URLs from OpenAlex.' It clearly differentiates from the sibling get_full_text by emphasizing URLs/links rather than content, and adds ordering and metadata details.

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 actionable guidance: 'Use your web tools to fetch publisher or repository links' and warns availability is not guaranteed. It clearly implies this tool returns links for fetching rather than content, though it does not explicitly name get_full_text as the alternative for full-text content.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds the key behavioral distinction that the response format depends on the chosen source – full metadata via OpenAlex versus compact graph metadata with citation counts via Inciteful. It does not cover error cases or rate limits, but given the annotations, this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with clear structure, no filler, and the core information front-loaded.

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 retrieval tool with read-only annotations and no output schema, the description covers the primary decision (source selection) and the identifier types. It lacks explicit return-value details but the high-level statement of 'full metadata' or 'compact graph metadata' gives the agent enough context 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?

The schema documents the id parameter's accepted formats, and the description reinforces it by naming DOI/OpenAlex ID/PMID, while also giving semantic meaning to the source parameter by describing what metadata each source returns. However, it does not elaborate on what qualifies as an 'Inciteful-supported identifier', leaving some ambiguity for that parameter.

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 ('Retrieve'), a resource ('paper'), and the two data sources with their metadata types, which clearly distinguishes it from sibling tools like get_abstract and get_full_text that target different content.

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 implies the tool is for retrieving a paper by identifier and contrasts OpenAlex (full metadata) with Inciteful (compact graph metadata), but it does not explicitly state when to choose this over alternatives like search_papers or get_abstract, nor when not to use it. The usage context is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: identifier resolution batching, deduplication, distance-2 similarity, seed exclusion from rankings, and the heuristic nature of labels. It also states 'No persistent review state is stored,' which reinforces the idempotent/read-only behavior. This goes beyond what annotations alone communicate.

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 moderately long but each sentence conveys distinct information: the core function, the iterative usage pattern, the batching/dedup behavior, the distance parameter, label heuristics, and the lack of persistent state. It is front-loaded with the main purpose and doesn't contain filler. It could be slightly more concise, but the density is justified given 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?

The description covers the essential operational aspects: the seed range, the ranking types, the iterative expansion, the distance-2 rule, seed exclusion, label heuristics, and statelessness. It does not detail the exact structure of the returned rankings or the output schema (which is absent), but for a complex tool it provides sufficient context for an agent to understand what it does and how to use it iteratively. Minor gaps remain in return format, but the description is relatively complete for the given complexity.

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 input schema itself provides descriptions for parameters, including the 'ids' field with supported identifiers and the 'sections' enum. The tool description does not add deeper parameter semantics beyond mentioning 'seed papers' as a general concept. Since the schema carries the parameter documentation (despite the 0% coverage metric referring to the description), a baseline of 3 is appropriate – the schema does the heavy lifting, and the description doesn't conflict or add much.

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 tool's purpose: it builds and queries a literature-review graph from 1-500 seed papers and returns rankings of papers, authors, institutions, and journals. The verb 'build and query' is specific, and the resource is well-defined. It distinguishes itself from siblings like 'similar_papers' or 'discover_papers' by focusing on a graph built from seeds and returning aggregated rankings.

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 explicit usage guidance: 'To add papers, call again with the returned seed_ids plus selected result paper_id values.' It also notes that multi-seed similarity uses distance 2 and seeds are excluded from rankings. However, it does not explicitly state when this tool is preferred over siblings or when not to use it, leaving some room for inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds value by disclosing the pagination behavior via next_cursor and indicating that the tool returns metadata. This is useful context beyond the annotations, though it does not address limits, ordering, or API-specific quirks.

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 concise sentences with no filler. The core purpose is front-loaded, and the pagination and follow-up usage details are packed efficiently.

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 read-only search tool, the description is minimally adequate, and annotations cover safety. However, with no output schema, it does not explain the returned metadata fields, how pagination actually works, or how to combine filters with the query. It also does not differentiate from sibling discovery 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 only 25%, with only the filter parameter having a description in the schema. The description adds partial meaning by mentioning next_cursor for pagination, which hints at the cursor parameter, but it does not compensate for the lack of documentation on limit, query semantics, or cursor usage syntax.

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 and resource ('Search OpenAlex for papers by topic or title'), which clearly identifies the tool's core purpose. It also distinguishes itself from downstream tools like get_paper and similar_papers by mentioning their role in using selected IDs, but it does not explicitly contrast with sibling search/discovery tools such as discover_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 implies when to use the tool: when searching by topic or title, and it provides a follow-up workflow ('Use selected IDs with get_paper or similar_papers'). However, it does not say when to choose this tool over alternatives like discover_papers or literature_review, and there is no explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context: the Inciteful citation-graph mechanism, optional OpenAlex enrichment via exact DOI matches, ID resolution to DOI/PMID, and the caveat that graph coverage may be narrower than OpenAlex. This goes beyond the annotations and helps set expectations.

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 focused sentences (~40 words) with no filler. The main purpose is front-loaded, followed by enrichment detail and a coverage caveat. Every sentence earns its place; it's both concise and well-ordered.

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 read-only tool with three parameters, annotations, and no output schema, the description covers the core behavior, how input IDs are handled, the optional enrichment, and a key limitation. It doesn't describe the response shape or the exact semantics of 'limit', but given the simplicity and the annotations, the agent has enough to invoke it correctly. A 4 reflects this nearly complete picture.

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 only 33% (only 'id' has a description). The tool description partially compensates: it clarifies 'enrich' via 'optionally enriched with OpenAlex metadata' and explains ID handling for 'id' ('OpenAlex IDs are resolved to DOI/PMID first'). However, the 'limit' parameter is left entirely undocumented, and no default/range context is given. The description adds some value but doesn't fully cover the gap, so a 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 clearly states it 'Find[s] related literature using Inciteful citation graph similarity,' which is a specific verb, resource, and method. It implies a similarity-focused search distinct from search_papers or get_paper, though it does not explicitly name a sibling it is not. Slightly more differentiation would earn a 5.

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 implies the use case (finding related literature) but offers no explicit guidance on when to prefer this over siblings like discover_papers or literature_review, nor when not to use it. It mentions the enrichment option but doesn't state conditions for choosing alternatives. This is adequate but leaves the agent to infer.

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