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

With no annotations provided, the description carries the full burden. It discloses critical behavior: uses a health cache, force_refresh bypasses cache, and URL filtering (only public/allowlisted). This adds significant value beyond the schema. However, it does not explicitly state whether the operation is read-only or any side effects.

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 fluff. The most important information (purpose, caching, URL restrictions) is front-loaded. 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?

For a simple tool with two parameters and no output schema, the description covers purpose, behavioral constraints, and parameter hints. It lacks explicit description of return values, but given the context, it is mostly complete for an agent to use correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains force_refresh's effect (ignores cache) and implies that the 'urls' parameter accepts only public/allowlisted URLs. However, it does not fully describe all parameter meanings or expected formats, leaving some ambiguity.

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 'probes Sci-Hub mirrors for availability', which distinguishes it from sibling tools like 'list_mirrors' that likely list mirrors. It also mentions caching and force_refresh behavior, making the tool's specific purpose unmistakable.

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 useful usage context: it only probes configured public mirrors or allowlisted https hosts, rejecting private/localhost URLs. This helps the agent determine when to use this tool and what inputs are valid. However, it does not explicitly compare to other tools like 'list_mirrors' or 'download_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?

No annotations provided, so description carries full burden. States return values and force re-download, but omits state changes, auth needs, error handling, or behavior on missing paper.

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

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

Three sentences, front-loaded purpose. Each sentence adds value. 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?

Covers purpose, sources, conditional behavior, and return fields. Missing error states, prerequisites (e.g., Sci-Hub access), and edge cases for 6 parameters.

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 parameters are already documented. Description adds context for 'query' types and 'force' meaning, but does not significantly enhance understanding beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Download an academic paper PDF by DOI, title, URL, or citation.' Specific verb and resource. However, does not explicitly distinguish from sibling 'download_papers' (plural).

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 conditional guidance for Unpaywall and 'force' parameter, but lacks when-to-use compared to siblings like resolve_doi or lookup_unpaywall. No explicit alternatives or scenarios.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It mentions deduplication of DOIs, writing scipdf-manifest.json, and returning indexed results. However, it omits details like error handling, overwrite behavior, concurrency, or authentication requirements. The disclosure is moderate but not exhaustive.

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 with three sentences, each adding value. It front-loads the purpose ('Batch-download papers'), then details input requirements, and finally lists key behaviors. No redundant or extraneous information.

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

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

Given five parameters, no annotations, and no output schema, the description lacks completeness. It does not explain the purpose of 'force' or 'outdir', default behaviors, or handling of errors. An agent would need to infer or experiment with missing details, making it insufficient for reliable invocation.

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

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

Schema description coverage is 60%, covering three of five parameters. The description adds context for the 'queries' parameter by listing accepted input types, but does not explain 'force' or 'outdir'. It provides marginal additional value beyond the schema for the covered parameters.

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 explicitly states 'Batch-download papers' and lists specific input types (DOIs, titles, URLs, bibliography blobs). It distinguishes from the sibling tool 'download_paper' by emphasizing batch operation. The verb 'download' and resource 'papers' are clear and 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 implies use for batch downloading via 'Batch-download' but does not explicitly state when to use this tool versus alternatives like 'download_paper' for single papers or other siblings. No when-not-to-use guidance or prerequisites provided.

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

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

With no annotations, the description carries full burden. It discloses that Crossref metadata is fetched, but lacks details on error handling, rate limits, or whether network access is required.

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, well-structured sentence that conveys all essential information without any waste.

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 one parameter and no output schema, the description adequately explains the function but does not specify the return format or behavior with invalid DOIs, leaving some gaps.

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 the 'doi' parameter described as 'DOI'. The description adds value by explaining that the DOI is used to fetch Crossref metadata, enhancing the schema's minimal 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 tool formats citations in specific styles (APA, GB/T 7714, BibTeX) using a DOI, which distinguishes it from siblings like resolve_doi or download_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 description implies usage when a DOI is available by mentioning 'from DOI', but does not explicitly state when to use this tool over alternatives like parse_references 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?

The description notes that the tool 'hot-reloads config', which is a behavioral detail beyond a simple list operation. However, it is unclear whether this is a side effect or the primary action. No annotations are provided, so the description bears full responsibility, but the phrase lacks clarity on the impact.

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

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

Single sentence, front-loaded with main purpose, no superfluous words. 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?

Despite no output schema, the description sufficiently outlines the return categories. It covers the main information an agent would need to invoke the tool. However, it could mention the format or that it returns a list.

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 no parameters, and the description clarifies what is listed (mirrors, PDF hosts, Unpaywall status, settings), adding value beyond the empty schema. Per guidelines, 0 params gets baseline 4.

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 it lists configured Sci-Hub mirrors, PDF hosts, Unpaywall status, and settings. The verb 'list' and the resource categories are specific. It also distinguishes from siblings like check_mirrors (which checks availability) and reload_config (which reloads config without listing).

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?

No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, when-not-to-use, or compare with sibling tools like check_mirrors or reload_config. The usage context is implied but not articulated.

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

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

With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It states the tool lists files but does not mention side effects (e.g., is it read-only? Does it modify anything?), permissions, or error handling (e.g., what if the directory is missing?). This is insufficient.

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, concise sentence that immediately conveys the core action and ordering. However, it could be slightly improved by front-loading the key benefit (listing PDFs) without sacrificing brevity.

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

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

Given no output schema and only 50% schema description coverage, the description should compensate with details about return format, default behavior, and limitations. It does not mention response structure, pagination, or behaviors like empty directory handling, leaving significant gaps.

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 covers 50% of parameters: 'limit' has a description, but 'outdir' has none. The description adds no new meaning beyond the schema—it does not explain what 'outdir' represents or default directory behavior. For an agent, this is ambiguous.

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 verb ('List'), the resource ('PDF files already in the download directory'), and the ordering ('most recent first'). It distinguishes itself from sibling tools like 'download_paper' (downloads) and 'list_mirrors' (lists mirrors), making the purpose 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?

No guidance is provided on when to use this tool versus alternatives. For example, it does not mention that this tool only lists existing files, while 'download_paper' fetches new ones. The description lacks any contextual cues for selection.

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

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

No annotations, so description must carry burden. It discloses non-destructive nature (does not download) and a requirement, but omits details like rate limits or error behavior.

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

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

Short, front-loaded sentence with essential requirement line. No filler, but could benefit from a bit more structure.

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 tool with one parameter and no output schema, the description adequately covers purpose, key behavior, and requirement. Lacks explanation of return format but is sufficient.

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?

Only one parameter (doi) with full schema description. Description adds no additional meaning beyond the schema, so 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?

Description clearly states the tool queries Unpaywall for Open Access status and PDF URL, specifying it does not download. This distinguishes it from siblings like download_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?

Explicitly states when to use (query OA status/URL) and notes the prerequisite environment variable SCIPDF_UNPAYWALL_EMAIL, providing clear context for invocation.

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?

Discloses it uses system default viewer, but omits error behavior (file not found), blocking nature, or return value. With no annotations, more detail expected.

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

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

One concise sentence front-loading action, perfectly sized for a simple tool.

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?

Simple tool with 1 param and no output schema; description covers purpose and method, but missing mention of return value or error scenarios.

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%; description adds only that path is 'local PDF' and mentions viewer, but doesn't add significant meaning beyond schema definition.

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 action (open), resource (local PDF path), and method (system default viewer with cross-platform specifics). Distinct from siblings like download_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?

No guidance on when to use this vs alternatives (e.g., after downloading), no prerequisites or exclusions stated.

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

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

No annotations are provided, so the description must fully convey behavioral traits. It only states that the tool extracts DOIs/queries, but it omits key details such as how it handles invalid input, what happens if no DOIs are found, whether it performs validation, or any rate limits. The description is too minimal for full transparency.

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

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

The description is a single, clear sentence that directly states the tool's function. It contains no unnecessary words or redundancy, making it efficient 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?

For a simple one-parameter tool with no annotations or output schema, the description is minimally adequate. It explains the input type and the extraction goal, but it lacks mention of the output format, success indicators, or error behavior. Additional context would be beneficial for confident usage.

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 the parameter description 'Bibliography text (bib/ris/plain)'. The tool description adds value by explaining that the text is parsed to extract DOIs/queries, providing context for the parameter's purpose. However, it could further clarify expected input format details or constraints.

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 extracts DOIs/queries from specific bibliography formats (BibTeX, RIS, plain text). The verb 'Extract' and resource 'DOIs/queries' provide specific scope, and it distinguishes itself from sibling tools like check_mirrors, download_paper, etc., which handle different tasks.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or when not to use it. The user/agent must infer its applicability from the sole purpose statement.

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

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

No annotations; description states 'hot-reload' and 'without restarting' which suggests non-destructive behavior. However, lacks details on prerequisites or side effects, which for a zero-param config reload is adequate but minimal.

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

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

Single sentence with no wasted words. Key information is front-loaded: action (hot-reload), source (environment variables and config.json), and benefit (without restarting).

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 zero parameters and no output schema, the description covers the essential behavior. Could mention that it targets scipdf config specifically, but completeness is high given simplicity.

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?

No parameters; baseline score of 4 applies as description adds no confusion and schema coverage is 100%.

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 'Hot-reload scipdf config from environment variables and config.json without restarting the process.' It specifies a specific verb (reload) and resource (config), and distinguishes from siblings which deal with papers and mirrors.

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?

Implies usage context: use when config changes should be applied without a restart. No explicit when-not or alternatives, but given zero parameters and sibling unrelated, guidance is sufficient.

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?

Without annotations, the description carries full burden for behavioral disclosure. It mentions using two sources and returning candidates when ambiguous, which is helpful. However, it does not disclose whether the operation is read-only, any authentication needs, or rate limits.

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

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

The description is two clear, concise sentences with no superfluous information. Every sentence adds value—the first states the purpose and sources, the second explains the ambiguity handling.

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

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

Given no output schema, the description is adequate for a simple lookup tool but leaves gaps, such as what the return format is (e.g., a string or object). It covers core behavior but could be more complete about error handling or response structure.

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 both parameters (query, query_type) with descriptions, achieving 100% coverage. The description does not add extra semantic details beyond what the schema 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 clearly states the tool resolves titles, URLs, or citations to DOIs using specific sources (Crossref, OpenAlex), and mentions handling of ambiguous results. This differentiates it from siblings like 'check_mirrors' or 'download_paper' which serve different purposes.

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 its use for resolving to DOIs but provides no guidance on when to choose this tool over others, such as 'lookup_unpaywall' for open access status. It does not explicitly mention 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.