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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context the annotations do not: parsed fields are unverified candidates, fields.year is only populated when quality.year=verified_by_pattern, and text attributed to another article appears under 'excluded' with its page. It still says nothing about pagination or result-size behavior.

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

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

Three sentences, front-loaded on the return shape with no filler, which is good. But the prose is heavily compressed and jargon-laden ('quality.year=verified_by_pattern', 'continuation-marker evidence') without explaining those terms, forcing the agent to decode terse internal vocabulary.

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

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

With no output schema, the description does a reasonable job characterizing the returned entry and candidate/excluded structure. But for a paginated list tool it omits pagination mechanics entirely and gives no hint about reference-list size or ordering, leaving a real gap for correct invocation.

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

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

Schema coverage is only 33% — offset and paper_id have no schema descriptions — yet the description spends all of its words on output fields and never mentions limit, offset, or how to page through a long reference list. The one documented parameter (limit, default 50) is documented in the schema, not the description.

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

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

The description states a specific resource and return shape: reference-list entries as printed (raw_text) with PDF page numbers, plus rule-parsed candidate fields. An agent can tell this returns bibliography entries rather than page images or structure, but it never names a sibling (e.g. get_paper_structure) to sharpen the boundary.

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 explicit when-to-use or when-not guidance and no alternative tool is named. The closing note ('A citation says nothing about inheritance or experimental comparison') is an interpretation caveat, not routing guidance, so the agent must infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured information: the distinction between native PDF bookmarks and inferred headings, that inferred items are flagged in the result, and that they may be inaccurate. What it omits is the cost/latency of structure extraction and whether a paper_id with no index entry errors or returns empty.

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 dense sentence lists the returned facets, front-loaded with the most concrete items, followed by one short caveat sentence. Nothing is redundant, though the run-on enumeration is harder to scan than a short bulleted list would be.

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

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

For a single-parameter read-only introspection tool with no output schema, the description must convey the return shape, and it does so as a facet list rather than a structured field mapping. The absence of an output schema means agents still cannot tell exact key names or nesting. Adequate for choosing the tool, thin for consuming its result.

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

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

There is exactly one parameter and the schema documents none of its semantics (0% coverage), so the description carries the burden. It does not explain paper_id, but the tool-level framing (this operates on a single paper's PDF) plus the strictly patterned id format in the schema makes the parameter's meaning derivable. No additional syntax or format detail is offered, keeping this just below full marks.

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 resource (paper structure) and enumerates its components: page count, native bookmarks, inferred section headings with pages, per-page text coverage and quality flags, References location. This clearly distinguishes it from siblings like read_paper_pages (raw text) or get_paper_references (reference listing). It lacks an explicit verb ('Get/Return'), but the enumeration makes 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?

The description never states when to use this tool versus read_paper_pages, render_paper_page, or search_papers, nor does it mention prerequisites or what to do if the structure looks wrong. The caveat that inferred items 'may be wrong' hints at a follow-up path but does not name an alternative tool. Usage must be fully inferred.

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 annotations by disclosing a real side effect ("Indexes not-yet-parsed PDFs on first call"), the de-duplication key, the exact fields returned, and an explicit non-return ("Never returns full text"). The first-call indexing is a write to a local cache that readOnlyHint does not cover, so surfacing it is genuinely valuable context rather than a restatement.

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

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

Three dense sentences, front-loaded with the core action and scope, then side effect, then return contract. No filler and nothing repeated from the schema.

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

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

For a zero-required-param listing tool with no output schema, the description covers corpus, de-duplication, return fields, and the indexing side effect. The one gap is pagination: with limit/offset present it never says whether a total count is returned or how the agent should decide it has listed everything.

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

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

The schema documents all three parameters (limit, query, offset) at 100% coverage, so the baseline is 3. The description adds nothing about filtering or paging behavior — notably it never says whether `query` narrows the listed set or how `offset`/`limit` interact with de-duplication.

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 ("List PDFs in the configured literature folder") plus the scope qualifier of SHA-256 de-duplication, so the agent knows exactly what corpus is enumerated. It implicitly separates itself from read_paper_pages via "Never returns full text", but it never names search_papers or the other siblings as the alternative for filtered retrieval.

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 only implied: an agent can infer this is the browse/enumerate entry point before calling read_paper_pages or get_paper_structure. There is no explicit when-to-use versus search_papers, and no stated exclusions or prerequisites (e.g. that the folder must be configured).

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 a safe, non-open-world read, so this earns credit for the extra behavior it discloses: a hard 10-page-per-call cap that is not encoded in the schema, output bounding via max_chars, and the exact shape of truncation metadata ('next' = start_page + char_offset). The 'PDF text layer only' caveat is a useful reliability warning that annotations cannot 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?

Three tight sentences, front-loaded with what the tool returns, followed by pagination mechanics and the one caveat. No filler and no restatement of the tool name.

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

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

With no output schema, the description still tells the agent what comes back (per-page text with real page numbers) and how to resume after truncation. Combined with the page-range cap and the fidelity caveat, nothing material for a correct call 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?

Coverage is only 60%, and the description fills the critical gaps: it supplies the 10-page limit that the schema's end_page maximum does not enforce, explains max_chars as an output bound rather than a filter, and defines char_offset/start_page as a continuation pair driven by the returned 'next' value.

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 (text of a page range), plus scope constraints: 1-based indexing, max 10 pages per call, and per-page separation keyed to real page numbers. It also implicitly separates itself from render_paper_page by noting it reads the PDF text layer only.

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

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

Gives explicit routing guidance to the sibling render_paper_page for verifying formulas and tables, and explains the continuation path when output is truncated. It does not address the other siblings (search_papers, get_paper_structure), but the primary alternative for this decision is clearly named.

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, it discloses the key behavioral facts: PDFs are never modified, force=true re-parses everything while the default only handles new/changed files, and a single failing file does not abort the batch. These are consistent with readOnlyHint=false, idempotentHint=true and destructiveHint=false. It omits how long a forced full re-parse takes and what the call returns, which keeps it from a 5.

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

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

Four short sentences, each contributing a distinct fact: purpose, safety guarantee, parameter semantics, and failure isolation. The core action is front-loaded and nothing is repeated.

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 one-parameter, non-destructive maintenance tool with no output schema, the description covers purpose, side effects, parameter behavior and error handling. The only real gap is that it does not say what a caller learns from the result (e.g., counts of parsed or failed files), which matters given failure isolation is advertised.

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

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

Schema coverage is 0% for the single parameter, so the description carries the full burden and does: 'force=true re-parses every paper; otherwise only new/changed files are parsed.' This gives both the meaning and the default behavior, which the bare boolean schema does not.

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 pair: 'Rescan the PDF folder and (re)build the local derived cache.' That immediately separates it from read-only siblings like list_papers or search_papers, which consume the index rather than build it. It stops short of naming any sibling explicitly, so an agent must infer the relationship.

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

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

Usage context is implied rather than stated: the incremental-by-default behavior suggests it is safe to call routinely, and force=true implies a rarer full rebuild. There is no explicit 'call this when X' or guidance on when another tool is the better choice. An agent can infer intent but is not told preconditions or cost trade-offs.

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=false, so safety is covered; the description adds genuinely new behavior — the PNG output format, the scale range/default, and the 2400 px longest-edge cap that can silently downsample output at high scales. It does not mention rendering latency or failure modes for out-of-range pages.

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

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

Two short clauses, front-loaded with the core action and output format, followed by constraints. No filler, and every clause carries usable information for invocation.

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

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

For a read-only, single-parameter-set rendering tool with no output schema, the definition covers what is produced, how large it can be, and why an agent would want it. The remaining gap is minor: it never confirms the image is returned inline versus as a path/URL, which matters for a binary-producing tool.

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

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

Schema description coverage is 0%, so the description must carry the load; it does well for scale (range 0.5–3, default 1.5, and the resolution cap) and conveys that page is a single page number. It adds nothing about paper_id's required format (^p[0-9a-f]{16}$) or that page numbering is 1-based, leaving two of three parameters partially or wholly undocumented.

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 (render) and resource (ONE page) plus the output artifact (PNG image), so an agent knows exactly what it produces. The emphasis on 'ONE' implicitly contrasts with the multi-page sibling read_paper_pages, and the parenthetical use cases ground the tool concretely.

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 parenthetical use cases (checking formulas, tables, figures, two-column reading order) give clear situational context for selecting this tool over text-extraction siblings. It stops short of naming an explicit alternative or stating when not to use it, so it falls just below the top tier.

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 readOnlyHint/openWorldHint, it discloses the exact matching algorithm, the AND-across-terms rule, the 200-char query cap, and the return payload shape (paper_id + page + snippet). It does not state the search scope when paper_ids is omitted (all papers vs. an indexed subset) or how limit interacts with hit ordering, but the behavioral core is disclosed.

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

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

Three dense clauses, front-loaded with the operation and followed by the matching rules and the next-step hint. No filler, no restatement of the tool name or title.

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

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

With no output schema, the description usefully explains the return shape itself, and the matching semantics cover the hardest-to-guess behavior. The remaining hole is scoping: an agent cannot tell whether omitting paper_ids searches the whole library or only the current context.

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

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

Schema description coverage is only 33%, so the description is expected to compensate. It explains the query parameter's semantics and length limit well, but says nothing about paper_ids (that it restricts the search to specific papers) or limit (default 20 is only in the schema), leaving two of three parameters uninterpreted.

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?

"Keyword search over page text" gives a specific verb (search) and resource (page text), and the parenthetical spells out the matching model precisely (Chinese/English substring, whitespace/width-insensitive, AND across terms). No sibling performs search, so the tool is unambiguous without needing disambiguation.

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 names the downstream step explicitly ("re-read hits with read_paper_pages"), which tells the agent this is a discovery tool, not a retrieval tool. It stops short of contrasting with list_papers or get_paper_structure, so an agent browsing broadly still has to infer when keyword search beats enumeration.

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