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

Beyond the readOnly/openWorld/non-destructive annotations, it discloses fan-out across S2/OpenAlex/EPO OPS/Open Library, auto-detection of patent numbers, and the async job-handle behavior. These are substantive behaviors not inferable from 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?

Four dense sentences with no fluff: purpose first, then upstream routing, then asynchronous behavior. Each sentence earns its place, and the structure front-loads the action.

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 batch tool with a rich schema and annotations, it covers the essential operational facts: supported ID types, upstream fallback/configuration, and the expected job-handle flow. With an output schema present, nothing critical 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%, and the input schema already fully documents identifiers and fields, including examples and the enum. The description adds no new parameter-level semantic guidance; it merely restates identifier categories already present.

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 opens with a precise verb-object statement: 'Resolve a list of paper, patent, or book identifiers to full records.' It distinguishes itself from single-item siblings by emphasizing batch/list behavior and the S2 batch endpoint; the explicit identifier scoping makes selection unambiguous.

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 clear usage context: expected identifier types, upstream routing, and the fact that large batches return a job handle to poll with get_job_result. It does not explicitly name single-identifier alternatives or state when not to use this tool, preventing 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?

Annotations already indicate read-only and non-destructive behavior; the description adds useful details about caching and background job handling. It does not disclose potential rate limits or failure modes, but the core behavior is transparent.

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 concise sentences cover purpose, resolution, caching, and async behavior without redundancy. The structure is focused and easy 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?

Given the output schema exists, the description adequately covers what the agent needs: input semantics, behavior, and async result retrieval. No critical context appears 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?

Both parameters are fully described in the schema, with identifier format and valid field options explicitly listed. The description reinforces identifier semantics by mentioning DOI resolution.

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?

Clearly states the tool fetches OpenAlex metadata to supplement Semantic Scholar data, using a specific verb and resource. The distinction from siblings like get_paper and search_papers is evident through the OpenAlex enrichment focus.

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?

Describes the enrichment purpose and the asynchronous behavior with get_job_result, giving practical usage context. It could more explicitly contrast with nearby tools like get_paper, but the enrichment scope is clear enough.

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

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

Goes well beyond the read-only/open-world annotations by disclosing async execution (rate-limited, one request per node, commonly long-running), the job-handle return contract, and detailed partial-failure semantics including that a partial found:false is not proof of no path and a partial found:true is not guaranteed shortest. This is exactly the kind of behavioral context an agent cannot infer from the schema or annotations.

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

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

Front-loads the core purpose, then layers algorithm, execution model, and failure semantics in short paragraphs that each carry distinct information. Slightly long, but no sentence 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?

Covers everything needed to invoke and interpret the tool: what it computes, that it is asynchronous, how to retrieve the result, and how to read imperfect outcomes. With an output schema present, return-value detail is not required, yet the key job-handle behavior is still explained.

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 direction, max_depth, source_id, and target_id. The description adds only indirect meaning (one request per node relates to max_depth), leaving the baseline of 3 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 precise verb and resource ('Find the shortest citation path between two papers') and pins down the algorithm as BFS over the citation/reference graph. This is clearly distinct from single-hop siblings like get_citations/get_references, but it never explicitly contrasts itself with get_citation_graph, which an agent might otherwise confuse as the closer analogue.

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 strong operational guidance: the call returns a job handle to poll via get_job_result rather than the path, and it explains how to read partial results (partial flag, failed_requests, warning). It stops short of stating when to prefer this over get_citation_graph or other path/graph tools, so there are no explicit alternatives or exclusions.

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 destructiveHint=false, and the description is consistent with these (generating formatted output is non-destructive). Beyond that, the description adds genuinely useful behavioral context: enrichment fans out per paper, large batches can be slow, and such calls respond with a job handle rather than the citations themselves. This discloses the async/polling behavior that annotations do not capture. 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?

The description is front-loaded with the purpose, then the resolution/format pipeline, then the edge-case behavioral note. Every sentence earns its place; there is no filler. The async handling is placed last, which is correct since it only applies to large batches. Compact and well-structured for a tool with this many options.

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 definition covers the purpose, the multi-source resolution pipeline, the three output formats, and the job-handle behavior tied to get_job_result. The output schema exists, so return values need not be explained. The only minor gap is that the description does not explicitly differentiate itself from close siblings like batch_resolve or get_citations, leaving some selection reasoning to the agent.

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 each parameter (paper_ids, enrichment, citation_format) is already documented in the schema, including the enum values and defaults. The description adds marginal reinforcement by naming the resolution sources (Semantic Scholar/OpenAlex) and listing the output formats, which maps to the enrichment and citation_format parameters, but it does not add meaning beyond what the schema already conveys. 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?

The description opens with a specific verb+resource: 'Generate formatted citations for one or more papers,' and clarifies the pipeline (Semantic Scholar resolution, optional OpenAlex enrichment, output in BibTeX/CSL-JSON/RIS). It is clearly distinct from the sibling get_citations (which retrieves inbound citations, not formatted output), though that distinction is implied by the format emphasis rather than named 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?

The description gives concrete operational guidance: for large batches, enrichment fans out, so the call returns a job handle to poll via get_job_result instead of the citations. This tells the agent when to expect async behavior and points to the correct sibling. However, it never states when to prefer this tool over batch_resolve or enrich_paper, nor when not to use it — the routing to alternatives is left to inference.

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

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

The description discloses the asynchronous behavior: normal calls answer directly while long-running calls return a job handle to poll with get_job_result. It also mentions the up-to-5 candidate fallback for name searches, going beyond the readOnly/destructive 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 concise and well-structured: purpose first, then identifier behavior, then execution/async behavior. No unnecessary wording.

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 an output schema present, the description does not need to detail return fields. It covers the main call behavior, name-search disambiguation, pagination-relevant parameters, and the background job fallback, making it complete for the tool's 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?

Schema coverage is 100%, and the top-level description adds the conditional meaning of identifier: numeric S2 author ID triggers direct fetch, otherwise name search. The limit/offset descriptions already clarify they only apply to direct ID lookups.

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 fetches an author profile and publications or searches by name, and it explains the identifier-based branching behavior. This distinguishes it from paper/book/standard 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?

It provides clear context on when direct fetch versus name-search disambiguation is used, but it does not explicitly compare with alternative tools for author-related queries. Still, the guidance is unambiguous and actionable.

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?

ReadOnlyHint annotation is consistent; description transparently explains rate-limit behavior and download_cover side effects (cache, cover_error in read-only mode).

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?

Description is concise and front-loaded with the core purpose, followed by a brief, relevant note on rate-limiting and job polling.

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?

Covers key aspects an agent needs: input formats, side effects of download_cover, read-only mode behavior, and rate-limit resolution; output schema exists so not all return details need explanation.

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?

All three parameters are described with formats/examples; schema coverage is 100% and description adds meaningful detail like cover_path/cover_error 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?

Description clearly states the tool fetches book metadata by ISBN or Open Library ID, distinguishing it from siblings like get_book_excerpt and search_books.

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?

Mentions the polling fallback via get_job_result when rate-limited, giving practical usage context though not explicitly contrasting 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?

Annotations cover the safety profile (readOnly, non-destructive, open-world), and the description adds substantial behavior beyond them: the API cannot return full chapter text, excerpts are publisher summaries or search snippets, and it enumerates distinct error classes with retry semantics. That is exactly the contextual layer structured fields cannot carry.

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

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

It is front-loaded with the purpose and then the output limitation, with the error taxonomy last where it belongs. Slightly long for a one-parameter lookup, but each clause (no full text, error meanings) carries real decision value.

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-ISBN read tool with annotations and an output schema present, the description covers the remaining unknowns: what the excerpt actually is and how to interpret each error state. Nothing an agent needs to call or interpret this tool 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% with a single 'isbn' parameter already described as 'ISBN-10 or ISBN-13,' so the schema does the heavy lifting. The description adds no further parameter detail, making the 3 baseline 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 verb and resource ('Get a book excerpt and preview info from Google Books') and clarifies what the payload contains (publisher description, snippet, preview link). It implicitly separates the tool from get_book/search_books by framing it as excerpt-only, but never names those siblings 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 useful conditional guidance on outcomes ('not_found' means stop asking about that ISBN; 'rate_limited'/'upstream_error' are worth retrying), which effectively tells the agent how to react. However, there is no guidance on when to choose this over get_book or search_books, so context selection is left to inference.

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

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

Adds substantial context beyond the annotations: one rate-limited request per node, async job-handle return semantics, and a precise failure model where a failed upstream request yields stats.partial, stats.failed_requests, and a warning rather than aborting. It also disambiguates stats.partial from stats.truncated, which is exactly the kind of edge-case behavior an agent needs.

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

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

Front-loads purpose and scope, then layers on cost, async behavior, and the partial-vs-truncated distinction in distinct, purposeful paragraphs. Every sentence carries operational meaning with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, open-world traversal tool with an output schema, the description covers cost, async return, and the full failure-mode semantics. Combined with the output schema covering return shape, an agent has everything needed 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 description coverage is 100%, so every parameter is already documented in the schema. The description reinforces depth ('up to *depth* hops') and max_nodes ('hard cap') behaviorally, but adds no syntax or format detail beyond what the schema already supplies, 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: 'Traverse the citation graph from one or more seed papers', and immediately scopes it as BFS with depth hops returning nodes and directed edges. This distinguishes it from single-hop siblings like get_citations and get_references by making the multi-hop traversal explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly frames when the tool is heavy ('anything past a shallow, narrow graph runs long') and routes the agent to get_job_result for polling. However, it never explicitly contrasts with the closest siblings (get_citations, get_references, find_bridge_papers), leaving the choice between single-hop and graph traversal to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to repeat safety. It adds valuable behavioral context about deep pagination for min_citations, explaining that it can run long and returns a job handle to poll with get_job_result. This goes beyond the annotations and is useful for agents.

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 extremely concise: two sentences. The first sentence delivers the core purpose immediately, and the second adds a critical operational caveat. No filler or redundancy. Every word 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?

Given the output schema exists and annotations cover safety, the description is quite complete. It covers the primary operation and the non-obvious async behavior for min_citations. It does not describe error handling or rate limits, but these are not essential for an agent to invoke the tool correctly, especially with a rich input schema.

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

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

Schema coverage is 100%, so the baseline is 3. The tool description itself does not elaborate on any parameters; all meaning is derived from the input schema. While the schema is thorough (e.g., explaining min_citations client-side behavior), the description adds no additional parameter insight beyond what the schema provides.

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 ('Fetch papers') and the resource ('that cite the given paper'), and explicitly labels it as 'forward citations', which distinguishes it from backward-citation tools like get_references. The purpose is unambiguous and the wording is specific.

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 does not provide explicit guidance on when to use this tool versus alternatives such as get_references or get_citation_graph. It implies a distinction through 'forward citations' but does not state conditions or exclusions. The background-job note for min_citations gives some operational context but not usage 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?

The description adds context beyond annotations by explaining the polling nature, job expiration, and that cache hits return inline. The readOnlyHint and destructiveHint annotations are not contradicted; the tool is correctly presented as a read operation.

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 somewhat verbose but each sentence contributes useful information (purpose, usage, expiration, examples). It is well-structured, front-loading the primary purpose and then clarifying usage, without 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 simple one-parameter tool, the description fully covers when and how to use it, the parameter source, and behavioral expectations. The presence of an output schema completes the context, so 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?

The schema has no description for job_id, but the tool description explains it comes from the 'working' status response. This provides meaningful context for the parameter's origin, though it doesn't detail format or validation rules. It compensates well for missing schema coverage.

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 retrieves the outcome of a background job, using a specific verb and resource. It also explains when it is applicable (when a tool returns status 'working' with a job_id), distinguishing it from direct result tools like 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?

Explicit guidance is provided: call this tool when a tool responds with status 'working' and a job_id, poll every few seconds until terminal, and fetch soon after completion due to expiration. This is direct and actionable.

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 destructiveHint=false, so the safety profile is known. The description adds valuable context about caching, background processing, and the potential for returning a job handle instead of the paper, which is not covered by 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?

Two sentences with no filler. The core purpose is front-loaded, and the behavioral nuance (caching/background) is stated succinctly. Every word 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?

The description covers the two possible outcomes (immediate answer or job handle) and references the polling tool. Since an output schema exists, return format details are not needed. It does not mention error handling, but that is not critical given the other coverage.

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 fully documents the 'identifier' parameter with allowed formats (DOI, S2, arXiv, ACM, PMID). The description does not add extra semantic detail about the parameter itself; it only refers to 'full metadata' and the caching behavior, which is indirectly related. Since schema coverage is 100%, a 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 clearly states 'Fetch full metadata for a single paper', using a specific verb and resource. It differentiates from search_papers by specifying 'single paper' but does not explicitly name sibling tools like get_author or get_book, though the resource type makes it distinct.

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 explains the behavior when cached vs. not cached, and instructs to poll with get_job_result if a job handle is returned. This gives clear usage context, though it does not explicitly state when not to use this tool (e.g., for searching multiple papers) or mention 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?

Annotations already indicate read-only and non-destructive behavior. The description adds important extra transparency about long-running calls continuing in the background and returning a job handle to poll with get_job_result.

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 concise sentences with no filler; the core purpose is front-loaded and the background-job note is relevant and compact.

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 output schema exists and the input schema fully covers parameters, the description is complete enough. It includes the important asynchronous behavior; minor gap is not explaining the field preset options, but the schema already does so.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema's own descriptions for identifier, limit, offset, and fields, though the schema describes each parameter 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?

States a specific verb ('Fetch'), the resource ('papers referenced by the given paper'), and clarifies directionality with 'backward references', which differentiates it from siblings like get_citations.

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 'backward references' phrasing gives clear context for when to use this tool versus the forward-looking get_citations/get_citation_graph siblings, though it does not explicitly name the alternatives or give 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 declare readOnlyHint=true, so the safety profile is known. The description adds value by detailing the exact return fields and the conditional 'when configured' upstream version block, which is useful behavioral context beyond the annotation.

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, front-loaded with the primary purpose, followed by a practical usage note. Every word 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 simple zero-parameter read-only info tool, the description fully covers what the tool does, what it returns, and when to use it. The existence of an output schema further reduces the need to describe return format in detail.

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 has zero parameters, so the description doesn't need to explain parameter behavior. Baseline 4 is appropriate because there is no parameter ambiguity 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?

The description uses the specific verb 'Report' and identifies the resource ('wrapper and upstream version info'). It clearly lists the returned fields and distinguishes itself from sibling tools (which handle papers, books, etc.).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear use case: 'Useful for verifying a deployment matches the expected build.' This gives context for when to use it, though it doesn't explicitly mention alternatives or 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?

Goes well beyond the readOnlyHint annotation by explaining the async behavior (job handle), the failure mode (full_text_error), and the meaning of absent full_text/full_text_error. This covers side effects and edge cases clearly.

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 well-structured in short paragraphs and each sentence adds value. It is slightly verbose but not redundant, earning a high score for its efficient use of words.

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 fully covers the conditional return behavior (job handle vs. record), error states, and configuration prerequisites. Given the output schema exists and no nested objects are mentioned, this is sufficiently complete 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 coverage is 100% for both parameters, but the description adds operational meaning (e.g., 'if True and docling is configured' and the distinction between canonical and fuzzy identifiers), enriching the schema beyond the baseline.

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 the verb 'Retrieve' and the resource 'standard' clearly, and distinguishes from siblings like search_standards and resolve_standard_identifier by emphasizing retrieval by identifier (canonical or fuzzy).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear conditional guidance for fetch_full_text (returns a job handle when true, with docling configured) and mentions polling via get_job_result. Does not explicitly name alternative tools for when not to use this tool, but the conditions are reasonably 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?

The annotations already declare readOnlyHint and destructiveHint, but the description adds valuable behavioral context by specifying the output structure, the meaning of the 'errors' field (non-fatal), and the behavior when no sync has run (empty list). This goes 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 concise and well-structured. It states the purpose, defines key fields ('started_at', 'finished_at', 'errors'), and describes the return format and edge case (empty list) in a compact manner. Every sentence adds value.

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 (no parameters, no nested objects), the description fully covers what the agent needs: the output schema is described inline, including field meanings and the empty-list scenario. There is no missing context for invoking this 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?

The tool has zero parameters, so the description does not need to explain any. The baseline of 4 is appropriate, and no additional parameter-related information is missing.

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: 'Report the last sync run for each standards body.' It uses a specific verb ('report') and identifies the resource (sync runs per standards body). It also provides details on the return format, making it distinct from any sibling tool.

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?

While no explicit alternative is mentioned, the description makes the tool's use obvious: it is for checking the last sync status. Given that no sibling tool performs this function, clear context is provided without needing exclusions or contrasts.

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 destructiveHint=false, so safety is covered. The description adds meaningful context about the behavior: it uses the Open Library subject API and sorts results by edition count as a popularity proxy, which helps the agent understand the result ordering. This goes beyond the annotations, earning a 4.

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 the purpose front-loaded and no filler. It efficiently conveys the tool's function and the underlying logic, earning a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values are covered. The description explains the API and sorting, and the schema handles parameter details. It is complete for a read-only recommendation tool, though it does not mention potential edge cases or rate limits, which are minor given the annotations.

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 both 'subject' and 'limit' fully documented in the schema. The description does not add 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 clearly states the tool's purpose: recommending books for a subject via Open Library, and explains the underlying API and sorting criterion. It distinguishes itself as a recommendation tool, though it does not explicitly contrast with sibling tools like search_books or get_book, so it falls short of 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 when to use the tool (when you need popular books on a subject) by explaining the mechanism, but it does not explicitly state when not to use it or mention alternatives. It provides context but lacks explicit routing guidance relative to siblings.

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 the tool as read-only and non-destructive; the description adds a non-obvious execution trait: normal calls answer directly, but long runs switch to a background job with a handle to poll via get_job_result. This is valuable behavioral context beyond the annotations and helps an agent handle timeouts correctly. There is no contradiction with 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?

Two sentences with no filler: the first states the core purpose, the second states the execution behavior. Every sentence earns its place, and the async fallback is placed after the main purpose without bloating the description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a complete input schema, an output schema, and annotations covering safety, the main additional context needed—the synchronous-vs-asynchronous behavior and the polling route—is present. The only minor gap is explicit guidance on sibling alternatives, but that does not prevent an agent from invoking 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?

The input schema covers 100% of parameters with descriptions, including the 1-5 positive_ids constraint and the negative_ids default. The description only echoes 'positive/negative examples' and adds no extra parameter semantics beyond what the schema already provides, so the baseline score 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 the specific operation ('Recommend papers') and the input basis ('positive and optionally negative examples'), which clearly distinguishes it from sibling retrieval tools like search_papers, get_paper, and recommend_books. It states both the resource and the mode of operation, so an agent can tell exactly what the tool does.

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 right use case—having example paper IDs and wanting similar recommendations—but it does not explicitly state when to prefer this over search_papers or recommend_books, nor does it give exclusions. An agent must infer selection from the words 'papers' and 'examples' rather than receiving direct alternative 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?

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses important behavioral nuances: network fallback, cache-related performance degradation, and the possibility of returning a job handle (get_job_result) instead of the result. This adds significant context not captured by 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 well-structured and concise, with each sentence adding distinct value: purpose, algorithm, ambiguity handling, and performance caveat. No redundant or filler 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?

Given the tool's complexity (fallback logic, cache behavior, job polling), the description provides sufficient context for an agent to understand when to expect a direct result versus a job handle. It does not specify error conditions, but the output schema likely covers return structure. Overall, well-rounded for the 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?

The tool description does not add additional parameter information beyond the schema, which already provides a description for 'raw' (coverage 100%). The phrase 'messy standard citation string' loosely echoes the schema but does not expand on format, constraints, or examples. Baseline for full coverage is 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?

The description clearly states the tool's purpose: 'Normalise a messy standard citation string to its canonical form.' It uses a specific verb (Normalise) and resource (standard citation string), and further clarifies behavior with 'Returns all candidates when the input is ambiguous.' This distinguishes it from siblings like search_standards or get_standard.

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 some behavioral guidance (local regex first, fallback to APIs) but does not explicitly state when to use this tool over alternatives like batch_resolve or search_standards. It mentions the cold cache scenario and job handle, but lacks direct 'use this when...' or 'instead of...' instructions.

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?

Beyond the readOnlyHint annotation, the description discloses the rate-limit behavior and the possibility of returning a job handle instead of direct results. This is valuable behavioral context not present in 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 carrying distinct information: the search modes, the preferred parameters, and the rate-limit fallback. No redundant or filler 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?

With a fully described input schema and an output schema present, the description covers the core usage, the recommended parameter choices, and the edge case of rate limiting. Everything an agent needs to decide when and how to call this tool is addressed.

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 already fully describes each parameter with recommended usage. The description adds the cross-parameter guidance to prefer title/author over query, which slightly exceeds the schema's individual descriptions. No contradictions or missing clarifications.

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?

Clearly states the action (search) and resource (books), and lists the three supported search modes: title, author, or free text. Leaves no ambiguity about the tool's 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?

Explicitly advises preferring title and author over query for better results, and warns about rate limiting with a fallback to polling via get_job_result. This gives concrete, actionable guidance for when and how to use the 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?

The annotations already convey read-only and non-destructive behavior, and the description adds useful behavioral detail about latency and asynchronous fallback. It does not mention error cases, but the async and timing disclosure is meaningful 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 brief and to the point, with no redundant or filler content. Each sentence serves a purpose: identifying the action, setting latency expectations, and explaining the async path.

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 that an output schema exists and the annotations cover safety flags, the description provides enough context for correct invocation. The async behavior is the only non-obvious operational aspect, and it is explicitly covered.

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?

All parameters are described in the schema, so the baseline applies; the description itself adds little parameter-level detail beyond saying the search matches 'a query.' The schema already covers sort, filters, pagination, and field presets 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 tool searches Semantic Scholar for papers matching a query. It also distinguishes the normal direct response from the long-running fallback, making the tool's core purpose obvious relative to siblings like get_paper or search_books.

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 explicitly tells callers that the call usually completes in a few seconds and that long-running requests return a job handle to poll via get_job_result. This gives clear, actionable guidance on expected behavior and how to handle async results.

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?

The description explicitly discloses that a cold cache can cause the first call to exceed the soft deadline and that such calls return a job handle instead of the result, directing the agent to poll with `get_job_result`. This goes beyond the annotations (readOnly, openWorld) and provides critical runtime 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 paragraph that leads with the core purpose, then lists sources, explains the body parameter, and concludes with the performance caveat. It is concise, well-organized, and free of redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description includes the essential information needed to invoke the tool correctly: what it searches, the set of sources, the optional filter, and the potential asynchronous behavior on first use. Given the tool's simplicity and the presence of an output schema, this is sufficient for an agent to use it effectively.

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 already provides descriptions for all three parameters (query, body, limit) with 100% coverage. The description reiterates the body parameter's purpose and the query types, but adds no new semantic information beyond the schema. Baseline for full schema coverage is 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?

The description clearly states that the tool searches technical standards by identifier, title, or free text across NIST, IETF, W3C, and ETSI. It distinguishes from sibling search tools (search_books, search_papers) by specifying the subject domain and source bodies.

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 indicates when to use the tool (to search standards) and provides guidance on using the `body` parameter to restrict to a single source body. It also warns about the first call being slow and possibly returning a job handle, guiding the agent on handling asynchronous responses. However, it does not explicitly contrast with alternative search tools, so it is clear but not exhaustive.

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