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

With no annotations, the description carries the full burden and does so: it discloses a side effect ('appends an evidence line to the log'), the exact matching semantics (substring, no word boundaries, after normalisation q1), the text scope searched, and the auxiliary facts returned (version, sha256, licence, retraction status). This is substantially more than a bare 'check' verb would convey.

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

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

Front-loaded with the core purpose, then layered with scope, semantics, and caveats in separate sentences. Slightly verbose with parenthetical detail about normalisation, but every sentence carries usable information.

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

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

An output schema exists, so return values need not be spelled out, and the description still covers the write side effect, matching semantics, and the scope caveat needed to interpret a FOUND result correctly. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, giving a baseline of 3. The description adds only matching/normalisation context rather than new per-parameter meaning, so it does not rise above 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 a specific verb ('Check') and resource ('whether a quoted passage appears in the paper's pinned open-access PMC text'), which an agent can distinguish from siblings like retraction_status or record_support. The scope (PMC full plain-text file including header and references) is unusually precise.

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

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

Gives a clear exclusion ('It does not judge whether the passage supports the claim') and warns to check `paragraph` before attributing a FOUND passage, which is implied usage guidance. However, it never states when to prefer this tool over siblings such as record_support or verify_log, so routing 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?

With no annotations, the description carries the full burden, but it does disclose a real side effect: the search is recorded in the log. It says nothing about pagination, rate limits, or whether the log write can fail, so the behavioral picture is partial.

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

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

A single front-loaded sentence naming the action, resource, source, and side effect with zero 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?

An output schema exists, so return values need not be explained, and both parameters are documented in the schema. The description covers purpose, source, and the logging side effect, leaving only alternative-tool routing unaddressed.

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

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

Schema description coverage is 100%, so both parameters (identifier, limit) are already documented in the schema. The description only alludes to the identifier ('a paper') and never mentions the limit, so it adds little beyond structured data; baseline 3 applies.

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

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

States a specific verb ('List') and resource ('works that cite a paper'), plus the data source (OpenAlex), which an agent can act on immediately. It does not name or differentiate itself from the sibling search_literature, which is the nearest overlapping capability, so it stops 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?

There is no when-to-use guidance, no mention of when a different sibling (e.g. search_literature, resolve_identifier) is the better choice, and no prerequisites stated. The only usage signal is implied by the description's subject matter.

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

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

No annotations are provided, so the description carries the full burden. It does usefully disclose that the record is appended 'as a new line in the log', implying append-only, non-overwriting behavior. However it says nothing about permissions, idempotency, duplicate verdicts, or what happens if the referenced seq is invalid.

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

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

Front-loaded with the core action, followed by one clarifying sentence about what the tool does not do. No filler, though the line-broken prose is slightly looser than necessary for a three-parameter 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?

An output schema exists, so return values need not be described, and the append-to-log behavior is stated. But for a mutating tool with zero annotations, the description leaves permission requirements, error handling, and duplicate/conflicting verdict behavior unaddressed.

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

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

Schema description coverage is 100%, and the schema already documents seq, support, and by (including the enum values). The description only echoes the 'who gave it' idea, adding no format, constraint, or interpretation beyond the structured fields, so the baseline 3 applies.

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

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

The description gives a specific verb+resource: it records a support verdict about an evidence line, and it clarifies the semantics of 'support' as a verdict given by someone rather than computed. It implicitly separates itself from verification-style siblings (check_quote, verify_log) by stressing that litcheck computes no verdict, though it never names a sibling.

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

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

Usage is implied rather than stated: 'litcheck computes no support verdict itself; this stores one that was given' tells the agent this is the write path for an externally-supplied verdict, but there is no explicit when-to-use, when-not-to-use, or named alternative among the 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?

With no annotations, the description carries the full burden and does so well: it discloses the converter's PMC-only coverage, the Europe PMC fallback that applies to DOIs but not PMIDs/PMCIDs, and the exact meaning of NOT_FOUND and UNVERIFIABLE, including the important caveat that NOT_FOUND does not mean the paper is nonexistent.

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 core action is front-loaded in the first sentence, and the remaining sentences are dense but entirely devoted to failure-mode semantics that an agent cannot get elsewhere. No filler.

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

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

For a single-parameter tool with a full output schema and no annotations, the description covers everything an agent needs: what it converts, coverage limits, fallback behavior, and error-code interpretation.

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

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

Schema description coverage is 100% and the schema already documents the accepted formats (DOI, doi.org URL, PMCID, cued PMID). The description adds no syntax or format detail beyond that, 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 precise verb+resource: mapping one of DOI/PMID/PMCID to the other two via the PMC ID converter. The scope is narrow and unambiguous, and clearly distinct from siblings like search_literature, citing_papers, and retraction_status.

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

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

Usage is implied rather than stated: use it when you hold one identifier and need the others. It never names an alternative tool or an explicit when-not-to-use condition, so the agent must infer the routing from the sibling names.

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

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

With no annotations, the description carries the full burden and does so well: it defines NOT_RETRACTED_AS_OF, explains that it is only returned when the identifier resolved and all sources answered, describes the UNVERIFIABLE fallback, documents source-fallback behavior for papers not in PMC, exposes the `sources` field, and notes 'Not logged.' These are genuine behavioral traits beyond any structured field.

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

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

Front-loaded with the core question and behavior, then organized into status definitions and edge cases; every sentence carries information. It is dense and slightly long for a one-parameter tool, but the length is mostly justified by the status semantics that cannot live in the schema.

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

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

Output schema exists so return values need not be explained, yet the description still clarifies the `sources` field and the meaning of each status, fully covering the edge cases (non-PMC papers, missing DOI, unresolved identifiers). Nothing an agent needs to invoke and 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%, so the baseline is 3, but the description adds real semantics: it clarifies the identifier addresses a single paper and gives routing advice ('For a paper outside PMC, pass its DOI'), plus the requirement that the identifier resolve for a definitive status. That is meaningful meaning beyond the format examples in the schema.

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

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

Opens with a specific question-verb framing ('Is the paper retracted?') and names the exact mechanism ('Reads PMC's is_retracted flag and Crossref's notices'). An agent can distinguish this from siblings like check_quote or resolve_identifier, which concern quotations and identifier resolution respectively.

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

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

Gives clear routing context: 'For a paper outside PMC, pass its DOI,' and explains that corrections are excluded while expressions of concern are reported separately. It stops short of explicitly naming a sibling alternative or a when-not-to-use condition, so it is strong context without full exclusion guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the call has a persistent side effect (logging the query with a response hash), explains that hit_count reflects what the engine reported while items are only the first `limit`, and warns that a SEARCHED status with few items reflects the query rather than the field. It stops short of covering failure modes, auth, or engine-specific limits beyond litsense's cap of 100.

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 core action and its logging side effect are front-loaded in the first sentence, and every subsequent sentence adds interpretive value. The parenthetical about litsense and the 100 cap is slightly dense, but nothing is filler.

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

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

An output schema exists, so return-value documentation is not required, yet the description still clarifies hit_count vs items semantics, which is the main interpretive risk. For a three-parameter tool with a full schema this is close to complete, with only error/edge behavior left implicit.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the relationship between `limit` and the returned items and the distinct meaning of hit_count. The engine-specific syntax nuance is left to the enum descriptions rather than repeated here.

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

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

The description states a specific verb and resource ('Run one literature search') and adds the side effect ('record it, with its response hash, in the log'). No sibling tool performs a search, so it is unambiguously distinguishable from check_quote, resolve_identifier, citing_papers, 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?

Usage is implied by the fact that this is the only search tool among the siblings, and the note about missing papers hints at how to interpret results. However, there is no explicit 'when to use this vs alternatives' guidance, no prerequisites, and no statement of when not to call 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?

With no annotations, the description carries the full burden and does well: it discloses the detection model, its key limitation (unkeyed hashes; recomputed chains and truncated tails evade it), and an edge case (nonexistent log returns chain_ok false). It omits side-effect/read-only and cost/performance characteristics, which keeps it just short of 5.

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

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

Three sentences, front-loaded with the core action, followed by the value proposition and the adversarial-limitation caveat. Every sentence earns its place, though the limitation sentence is dense and could be split or tightened.

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-value documentation is not required, yet the description still usefully explains the chain_ok=false edge case. Combined with a zero-parameter schema, the definition is essentially complete; only security/side-effect framing is left implicit.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter syntax for the description to clarify, and it correctly adds no redundant parameter discussion.

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 and resource: 'Re-walk the log's hash chain and report the first line that does not fit.' It also states the exact output of interest (first failing line, if any), so an agent knows both the action and the result shape without opening the schema.

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

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

It implicitly defines the use case ('catches accidental and naive edits') and, importantly, states the condition under which the tool is NOT sufficient (rewrites that recompute later hashes or cut tails are only caught by comparing head_sha256 with an external copy). No sibling among check_quote/search_literature/etc. competes for this job, so explicit alternative routing isn't needed, but it stops short of saying when in a workflow to call it.

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