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

With no annotations present, the description carries the full disclosure burden and does well: atomic write, preservation of original encoding and line endings, and a backup location (.citecheck/backups) are all concrete behavioral traits. It doesn't state whether the rewrite is consumed/marked applied, idempotency, or failure behavior, which are meaningful gaps for a file mutation.

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 tight sentences, action and side effects front-loaded, with the gating condition as the closing clause. No filler and nothing redundant with 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 one-parameter mutation with no output schema, the description covers the essentials an agent needs: what it writes, the safety guarantees, and the approval prerequisite. Missing details about the applied rewrite's subsequent state and error cases are minor against what is provided.

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% for the single rewrite_id parameter, so the schema adds no meaning. The description never explains where rewrite_id comes from (presumably list_rewrites/propose_rewrite) or its expected form, though the name and surrounding workflow make it largely inferable.

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 ('Write a proposed rewrite into the manuscript file'), which clearly implies committing an existing proposal as opposed to propose_rewrite's drafting step. It does not explicitly name the sibling tools (revert_rewrite, discard_rewrite, list_rewrites), so the differentiation is inferential rather than spelled out.

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?

'Only call after the user approved the diff' is an explicit, actionable precondition that routes the agent correctly in the propose/approve/apply workflow. It stops short of naming the alternatives (e.g. use propose_rewrite first, discard_rewrite to abandon), which would make it 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?

No annotations are provided, so the description carries the full burden. It implies overwriting via 'replace a wrong match' but does not state whether an existing attachment is destroyed, what permissions are required, or whether the action is reversible. For a mutation tool with zero annotation coverage, this is a significant disclosure gap.

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

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

A single compact sentence with the core action front-loaded and the usage context trailing in parentheses. Every clause earns its place; nothing is wasted.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose and use cases. However, with no annotations it leaves behavioral edges (overwrite behavior, error cases, auth) unspecified, so it is adequate but not fully complete.

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 50%: pdf_path is documented in the schema, but key is not. The description's phrase 'to a reference' implicitly maps key to a reference identifier, partially compensating, but it adds no format or constraint detail. A 3 reflects the partial bridging of the coverage gap.

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 (attach), resource (local PDF), and target (a reference). This is a distinct action from any sibling tool like fetch_sources or record_verdict, so an agent can identify it. No explicit sibling differentiation is given, but the purpose is 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 parenthetical names two concrete situations for use: paywalled papers and replacing a wrong match. That is real when-to-use guidance. It stops short of naming an alternative tool or stating 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?

No annotations are provided, so the description carries the full burden, and it discloses only the aggregation dimensions. It never states that the call is read-only, that it is a computed summary rather than stored data, or what shape/grouping the counts take — though the three listed categories do convey the returned content at a high level.

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 a single compact sentence with the core concept (progress overview) front-loaded and the three dimensions enumerated, so every word earns its place. The sentence-fragment style and lack of a verb are minor demerits.

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 and no annotations, the description must explain the return content, which it partly does by naming the three per-status breakdowns. It omits the status vocabulary, the shape of the counts, and any read-only assurance — adequate but with clear gaps for a status/summary 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 input schema has zero properties, so there are no parameters to document; the baseline for a no-param tool is 4. The description does not need to add param syntax and nothing is missing or misleading.

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 fragment 'Progress overview: claims per status, sources per status, rewrites per status' states a specific aggregation resource and its three dimensions, so an agent can tell it apart from atomic verbs like get_claim or list_claims. It lacks a full verb phrase and gives no explicit sibling differentiation, but the resource is clear.

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 caller should prefer this over list_claims/get_claim or any other sibling, and no prerequisites. The closest thing to guidance is the implicit assumption that the caller wants a summary rather than raw records.

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 behavioral burden. It reveals that the tool may perform network calls via the online parameter but does not state whether the check is read-only, whether it mutates the .bib file, what permissions are needed, or how errors from Crossref are surfaced. For a tool combining network calls and file analysis with zero annotation coverage, this is a significant transparency gap.

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

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

A single, well-front-loaded sentence that packs the full scope without filler. The enumerative style is efficient, though the absence of punctuation beyond the initial colon makes it slightly dense; it remains readable and non-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?

The described checks are comprehensive for a bibliography audit, matching the complexity of the task. However, with no output schema and no annotations, the description omits how results are returned, whether the tool mutates files, and how it handles network failures, leaving gaps an agent would need to probe.

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 both parameters (keys, online) are already documented in the schema, including defaults and the Crossref scope. The description adds only the high-level framing of what online queries cover. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (the bibliography), then enumerates the exact classes of problems it detects: missing keys, unused entries, duplicates, missing DOIs, Crossref mismatches, retractions, and preprint-to-published cases. This is far more specific than any sibling and tells the agent precisely what it audits.

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 enumerated checks, but there is no explicit when-to-use or when-not-to-use guidance, and no routing to siblings like scan_uncited or fetch_sources which could overlap with certain checks (unused entries, DOI fetch). The agent must infer that this is the holistic bibliography audit 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?

With no annotations, the description carries the full behavioral burden, yet it only says a proposal is discarded. It does not state whether the discard is reversible, whether confirmation is needed, what happens if the rewrite was already applied or doesn't exist, or what permissions are required for this destructive 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?

A single short sentence with the scoping qualifier up front and no filler. Nothing is wasted; it is simply brief because the description is thin, not because it is padded.

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 mutation tool with no annotations, no output schema, and an undocumented parameter, the description is too sparse. It omits reversibility, error cases (already applied / not found), and any tie-in to the proposal lifecycle (propose_rewrite, list_rewrites, apply_rewrite) that an agent needs to invoke it safely.

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 one required parameter, rewrite_id, with 0% schema description coverage, so the description must compensate. It never mentions the parameter or what value is expected (an id from list_rewrites / propose_rewrite), leaving the identifier semantics implied at best.

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 (discard) and resource (a proposed rewrite), and the parenthetical '(not applied)' scopes it away from applied rewrites, implicitly separating it from revert_rewrite. It does not name the sibling explicitly, but the scope qualifier is enough for an agent to distinguish it.

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 phrase '(not applied)' implies usage: call this only for proposals that have not been applied, and use revert_rewrite for applied ones. That condition is implied rather than stated, and no prerequisites or exclusions are given explicitly.

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 discloses the output is 'self-contained HTML' and that a file is written, but says nothing about overwrite behavior of an existing path, permissions, or idempotency of repeated exports – significant gaps for a file-writing tool.

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 artifact first, with the report contents enumerated compactly. It is somewhat run-on at the end but no sentence is wasted.

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?

No output schema exists, and the description adequately conveys the report's contents and format. However, for a write tool with no annotations it omits when to invoke it and how it interacts with existing files, leaving meaningful 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 description coverage is 100% with 0 required parameters, so the schema already documents the path default and language default fully. The description adds no parameter detail beyond what the schema provides, making baseline 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 specific verb ('Write') and resource ('a self-contained HTML report') and enumerates what the report aggregates (claims, verdicts, verified quotes with page, rewrites, bibliography problems). This distinguishes it from the check-specific siblings like verify_quote or check_bibliography, though it does not name them 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?

There is no explicit when-to-use guidance, no prerequisites (e.g. checks must have been run first), and no alternatives named. The aggregating role is only implied by the surrounding sibling set.

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 disclose meaningful behavior: the ordered fallback chain, that text is extracted with page numbers and indexed, and that the run reports missing, paywalled, and title-mismatched PDFs. It stops short of stating the side effects explicitly (files written to disk, index mutation, possible network calls when download is enabled) or permissions/rate-limit considerations.

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 dense sentences with no wasted words; the resolution order and the reporting outcome are both front-loaded. Every clause earns its place by conveying either behavior or output content.

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

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

For a two-param, no-output-schema tool with no annotations, the description adequately covers scope, approach, and what gets reported back. It could add a note on side effects (persisted index/PDF files) to be fully complete for a state-mutating batch operation.

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 both parameters (keys, download) are already documented in the schema, including the open-access repositories relevant to download. The description adds no syntax or format detail for `keys` beyond what the schema provides, 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?

States specific verbs and resources ('Locate the PDF of each cited reference', 'extract its text ... and index it'), and spells out the resolution order (bib `file` field → PDF folders → Zotero storage → open-access repositories). This clearly distinguishes it from siblings like attach_pdf (manual attach) and read_source (read a single source), without needing to open any 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?

The multi-source fallback chain implies this is the batch-acquisition tool, and reporting on missing/paywalled sources hints at a verification workflow context. However, it never explicitly states when to use this versus attach_pdf or read_source, nor any exclusions or prerequisites (e.g., when to prefer manual attachment).

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. It usefully discloses the scoring method and the shape of each hit (exact text, page, surrounding context), but never states that it is a read-only operation with no side effects, nor whether it reads from disk/network or has any cost.

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 tight sentences with no filler; the purpose is front-loaded and the actionable instruction is last. Every clause carries 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?

No output schema exists, and the description compensates by describing the return fields (text, page, surrounding context) and how to use them. Nothing critical is missing for a 1-required-parameter evidence search, though a note on the claim_id/query relationship and read-only nature would make it complete.

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 80%, so the schema already documents key, query, claim_id and include_references. The description adds no parameter-level meaning beyond that (it mentions 'the claim' generically), 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?

States a specific verb and resource ('Rank the source's sentences') and the relevance criterion ('by relevance to the claim'), plus the retrieval method (BM25 + number matching). An agent knows exactly what this returns, though it does not explicitly contrast itself with siblings like verify_quote or read_source.

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: the closing instruction 'copy quotes verbatim from here' tells the agent this is the quote-sourcing step, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. read_source for full text, verify_quote to check a quote).

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 and no output schema, the description carries the full disclosure burden, and it does enumerate the returned fields (including source availability flags), which is genuinely useful. However it says nothing about error behavior for invalid claim_ids, permissions, or whether existing verdicts are mutable.

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 with a dense, comma-separated inventory of returns. No filler, though the list format loses a little readability.

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 getter with no annotations and no output schema, the return-field inventory compensates reasonably well. But the 'context' parameter's meaning and range are unexplained, leaving a gap an agent must resolve from the schema alone.

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% for 2 parameters. The phrase 'neighbouring sentences' hints at the role of the 'context' parameter but never connects it, and the 0-5 range/default of 1 is left entirely to the schema. claim_id is only self-explanatory by name.

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+resource ('Full detail for one claim') and enumerates the exact contents returned: plain text, raw LaTeX, neighbouring sentences, cited references, and verdicts. The singular 'one claim' implicitly distinguishes it from list_claims, though it never names the 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?

No when-to-use, prerequisites, or alternatives are stated. Nothing tells the agent to prefer this over list_claims when it needs a single claim's detail, nor that a claim_id must already be known.

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 carries the full behavioral burden but discloses little beyond 'paginated'. It does not state what pagination returns, the default filtering to cited-only sentences, auth/permission needs, or cost. The listing behavior is only implicitly conveyed.

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 with the verb and resource leading and no wasted words. It is appropriately sized, though it could sacrifice a word or two to add usage context.

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 6-parameter list tool with no output schema and no annotations, the description is minimal but conveys the shape of results. It omits usage guidance, pagination mechanics, and the cited-vs-uncited default, leaving clear gaps for an agent acting without structured support.

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 67%, so the schema already documents file, status, section and include_uncited, while limit/offset are undescribed there. The description adds only 'paginated', which loosely maps to limit/offset but gives no defaults or bounds. Baseline 3 is appropriate given partial 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?

States a specific verb (List), a clearly defined resource ('cited sentences (\'claims\')'), and the returned fields (keys, location, verification status). It is far clearer than a tautology, but it never distinguishes itself from siblings like get_claim or scan_uncited.

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 guidance, no prerequisites, and no mention of alternatives. The only operational hint is the '(paginated)' clause. An agent gets no help deciding this tool over get_claim or scan_uncited.

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 of behavioral disclosure. It never confirms this is a read-only operation or describes pagination, ordering, or result limits; the one behavioral hint ('with their diffs') largely restates what the existing output schema already covers.

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 short, front-loaded sentence with no filler or redundancy. It is efficient, though its brevity borders on under-specification rather than disciplined conciseness.

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 re-explained, and the tool is simple with one optional parameter. However, the description omits the status-filter semantics and any usage context, leaving meaningful gaps for an agent deciding between this and its many sibling tools.

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

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

The single 'status' parameter has 0% schema description coverage, so the description must compensate and does not — it never mentions that results can be filtered by status or what those enum values mean. The enum values (proposed/applied/reverted/discarded) are only self-explanatory because they mirror sibling tool names, not because the definition explains them.

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 ('List rewrites') and even indicates the content of the listing ('with their diffs'). It is clear what the tool does, but it does nothing to distinguish it from sibling listing/inspection tools like list_claims or audit_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?

There is no guidance on when to use this tool versus the many sibling rewrite tools (propose_rewrite, apply_rewrite, revert_rewrite, discard_rewrite) or the other listing tools. Nothing is said about filtering, ordering, or prerequisites, so the agent must infer all usage context.

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

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

With no annotations, the description carries the full burden, and it does substantive work: it discloses side effects (parsing sentences/citations/bibliography, restoring prior verdicts) and specifies the returned overview (language, counts, missing .bib keys). It does not state performance cost, failure modes, or whether restored verdicts can be reset, 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?

Two efficient sentences, front-loaded with the core verb and the re-open condition. Every clause carries information (behavior plus return shape). Minor density in the middle sentence keeps it just below maximal.

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?

There is no output schema, so the description correctly describes the return value (language, counts, missing .bib keys), and it explains the side effects of loading. Combined with full schema coverage, an agent has enough to invoke it, though it lacks any note on dependencies with sibling tools that consume the opened project.

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 all three parameters (bib, pdf_dirs, manuscript) are already documented in the schema, including that \input/\include files are followed. The description adds no parameter-level detail beyond this, 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 ('Open ... a manuscript') and enumerates the concrete work done: parsing sentences, citations, bibliography, and restoring previous verdicts. This clearly positions it as the session/entry-point loader, distinct from read_source, verify_quote, or check_bibliography. It could be sharper by explicitly naming a sibling it is not, but the purpose is 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 parenthetical '(or re-open after edits)' implies a when-to-use condition, but there is no explicit statement of alternatives, prerequisites, or when-not to call it (e.g., whether it must precede verify_quote/record_verdict). Guidance is implied rather than spelled out.

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 must carry the behavioral load. It does disclose the key trait that the proposal is staged and later 'applied with apply_rewrite,' implying reversibility via discard/revert siblings. It says nothing about permissions, validation of the claim/sentence target, or what happens if the anchor sentence doesn't exist.

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 sentences with the action front-loaded and zero filler. 'like any rewrite' is slightly vague but functional, and nothing is wasted.

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 core action and its follow-up step, which is the most important missing piece for a staged-mutation tool. It omits what the call returns (a rewrite handle?) and how the proposal is inspected or discarded, which the sibling set suggests matters.

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 50%: new_text and after_claim_id are documented, while note and language are undocumented in both places, and the description does not compensate. It also loosely calls the anchor an 'existing sentence' when the parameter is a claim_id, adding only marginal meaning over 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?

States a specific verb and effect: 'Propose new text after an existing sentence,' which is clearly distinct from the sibling propose_rewrite (which replaces existing text rather than inserting). It does not name propose_rewrite explicitly, but the insertion semantics are 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 second sentence ('Applied with apply_rewrite like any rewrite') gives useful workflow context — that this stages a change rather than committing it. However, it never states when to choose this over propose_rewrite, nor any prerequisites, so usage is only implied.

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 disclose meaningful behavior: validation of LaTeX constructs, citation-key preservation, and .bib membership, plus the fact that nothing is persisted until apply_rewrite. It omits what happens on validation failure (rejected vs. returned with warnings) and whether the proposal is stored and retrievable, which are the remaining behavioral gaps for a mutation-adjacent tool.

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, zero filler, and the scope constraint is front-loaded before the validation contract and the deferral note. Every clause carries 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?

There is no output schema, so the description must cover returns and it partially does by framing this as a non-persisting proposal gated behind apply_rewrite. It is nearly complete for a 5-parameter tool, with only failure semantics and proposal lifecycle left unstated.

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 80% and the schema already documents note, language, new_text and allow_citation_changes, so the baseline is 3. The description's citation rule ("none lost, all new ones in the .bib") gives useful context for why allow_citation_changes exists, but it adds no syntax, format or default details beyond what the schema supplies.

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+resource with bounded scope ("Propose a replacement for one sentence") and explicitly names the sibling apply_rewrite as the separate commit step. An agent can distinguish this from apply_rewrite, revert_rewrite and propose_insertion without opening any 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?

The phrase "Nothing is written until apply_rewrite" clearly establishes the propose-then-apply workflow and implicitly tells the agent when this tool (not apply_rewrite) is the right call. It does not, however, contrast with the adjacent sibling propose_insertion or state when a rewrite is appropriate versus an insertion.

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 carry the full behavioral burden. It discloses the paginated/sentence-based reading mode, but does not explicitly confirm read-only safety, describe permissions or rate limits, explain the return format, or mention error behavior for a page/sentence that doesn't exist.

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 with no filler. The core purpose and reading modes are stated immediately, and the examples earn their place by clarifying intent.

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 four parameters, no annotations, no output schema, and only 50% schema description coverage, the definition leaves key and max_sentences unexplained. It is not complete enough for an agent to confidently call the tool without inferring the missing parameter meanings.

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 50%. The description references the page and from_sentence modes, which loosely maps to the page and from_sentence parameters. It adds no semantics for the key parameter or max_sentences, so it only partially compensates for the undocumented half of 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?

The description states a specific verb (Read) and resource (a source), and describes the reading modes (page by page or from a sentence id). It does not explicitly differentiate from siblings like fetch_sources or find_evidence, so sibling routing is left to inference.

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 examples ('the abstract, or around a search hit') imply common use cases, giving some usage context. However, there is no explicit guidance on when to prefer this tool over alternatives such as fetch_sources or find_evidence, nor any 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?

With no annotations, the description must carry the behavioral load. It does disclose a real trait – every quote is checked against the PDF and the verdict is rejected if a quote is not verbatim – which is more than the schema states. But it omits what 'rejected' looks like (error vs. silent drop), whether re-recording overwrites a prior verdict, and any permission requirements.

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 tight sentences, the core action front-loaded and the enforcement rule immediately after. Nothing is padding and nothing needs to be re-read.

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 7-parameter mutation tool with no annotations, no output schema, and 57% schema coverage, the description is adequate but thin. It never says what is returned on success, whether recording is idempotent, or how claim_id/key relate to the sibling lookup tools, leaving real gaps for an agent wiring this into a workflow.

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 57%, with the verdict enum, quotes, and issues well documented in the schema itself. The description's verbatim-quote rule adds meaning to the quotes parameter, but claim_id, key, and confidence remain undescribed in both places, so it only partially compensates.

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+scope: 'Record the verdict for one (claim, key) pair.' That is precise enough to distinguish it from read-oriented siblings like get_claim or list_claims, though it never names a sibling explicitly 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?

Usage is implied rather than stated: the quote-verification precondition tells the agent when the call will succeed, but there is no explicit 'use this after X' or comparison to alternatives such as verify_quote or audit_status. An agent can infer the workflow but must supply the context itself.

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 says 'undo' but does not disclose whether the revert requires authorization, whether it is reversible, whether it restores prior text, or what happens to the rewrite record afterwards. For a mutation tool with zero annotation coverage, this is a substantial gap.

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

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

A single short sentence with no filler, front-loaded with the action. It is efficient, though arguably too terse for a mutation tool, so it falls short of a full 5.

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 mutation action, no annotations, no output schema, and an undocumented parameter, the description omits most of what an agent needs to invoke this safely. It should at minimum state the precondition and the effect on the underlying claim text.

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?

One parameter with 0% schema description coverage, so the description must compensate and does not. It never explains what rewrite_id is, whether it refers to an applied rewrite specifically, or where the agent obtains it.

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 clear verb ('undo') and resource ('an applied rewrite'), so the agent knows this reverses an already-applied rewrite. It does not, however, distinguish itself from close siblings like discard_rewrite or propose_rewrite, leaving the agent to infer 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?

The phrase 'applied rewrite' hints at the precondition, but there is no explicit when-to-use guidance and no mention of alternatives such as discard_rewrite or apply_rewrite. Given four sibling rewrite tools, this omission is significant.

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 it does disclose one valuable trait: results are heuristics and the host must judge each candidate (i.e., expect false positives, not verdicts). It does not address read-only safety, scope (whole project vs. a file), or the shape of what is returned.

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 compact sentences, front-loaded with the core action and examples, with the heuristic caveat reserved for the end. No filler, though the phrasing is slightly terse for the amount of schema burden it must carry.

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 two-parameter, no-annotation, no-output-schema tool, the description covers purpose and the candidate/heuristic caveat but omits any explanation of the file vs. project scope and the limit behavior. Adequate but with clear gaps an agent would want filled.

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% for two parameters, so the description must compensate and it does not: neither 'file' (optional, default null) nor 'limit' (default 30, max 100) is mentioned at all. The agent gets no hint that 'file' scopes the scan or that 'limit' caps candidates.

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 (Find) and resource (sentences without citations that look like factual claims), with concrete examples of the patterns it matches (numbers, comparisons, 'studies show' wording, EN/PT). This is clearly distinguishable from verification-oriented siblings like verify_quote or check_bibliography, though it never names an alternative 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?

Usage is implied: it surfaces candidates for later judgment, which fits as a pre-screening step before tools like verify_quote or find_evidence. However, there is no explicit statement of when to use it versus those siblings, and no exclusions or prerequisites are given.

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 usefully discloses the fuzzy matching tolerance for PDF artifacts, the 90/100 threshold, and what is returned (page and exact passage), but says nothing about failure behavior, permissions, or what happens when no match is found.

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 tight sentences, the core purpose front-loaded, and every clause (tolerance, threshold, return content) adds information without padding.

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 two-parameter verification tool with no output schema and no annotations, the description covers mechanics and return content but omits the meaning of 'key' and any failure/no-match behavior. Adequate but with a clear gap.

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 50%: the 'quote' parameter is documented (including the '...' joining syntax) but 'key' has no schema description and the description never explains it. The description does not compensate for the undocumented parameter.

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

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

States a specific verb and resource ('Check that a quote is really in the source') and adds scope detail (fuzzy tolerance, threshold). It distinguishes the operation from sibling read/scan tools by naming quote verification, but does not explicitly contrast with close siblings like find_evidence or check_bibliography.

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

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

The description implies the tool is for confirming quotes exist, but gives no when-to-use guidance, no alternatives, and no prerequisites. With siblings such as find_evidence and check_bibliography, an agent gets no routing help.

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