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

With no annotations, the description carries the full behavioral burden and does add value by disclosing rejection conditions (original PDFs, stale files, non-highlight annotations) and an approval gate. However it omits the permission/auth model, what side effects or irreversible changes occur on success, and what a successful result looks like.

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, zero filler, and the core action plus its approval gate are front-loaded. Efficient, though the brevity borders on under-specification for a 4-parameter mutation 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?

For a mutation tool with 4 undocumented required params, no annotations, and no output schema, the description is thin. It should explain the fingerprint/identity param, what 'stale' means operationally, and the success/error outcome, none of which are covered elsewhere.

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% and all four required parameters (file, page, xref, expected_fingerprint) are undocumented. The description only hints at the singular target via 'ONE existing highlight'; it never explains the fingerprint's role or how page/xref identify a highlight, so it fails to compensate for the schema 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 and resource ('Remove ONE existing highlight') with the singular scope emphasized, which is more precise than the bare name. It implies the apply/propose split vs siblings like propose_annotation_removal, but never names or contrasts 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?

Gives a real workflow precondition ('after explicit user approval') and a set of exclusions ('refuses to edit original PDFs, stale files, and non-highlight annotations'). It stops short of naming propose_annotation_removal as the intended preparatory step, which is the most relevant alternative an agent would weigh.

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. It discloses meaningful safety constraints (user approval required, fingerprint freshness, do not use shell commands to delete or reconstruct the PDF), but says nothing about reversibility, side effects on other annotations, or failure modes when the fingerprint is stale.

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 short lines, front-loaded with the core action, then prerequisites, then the safety prohibition. Every sentence earns its place and nothing is 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 mutation tool with no annotations, no output schema, and 0% schema coverage across six parameters, the description covers workflow and safety but leaves parameter meaning and post-call effects unaddressed. Adequate on workflow, incomplete on invocation detail.

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

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

Schema description coverage is 0%, so the description must explain six undocumented parameters. It only gestures at expected_fingerprint ('fresh fingerprint') and the file prerequisite ('*-annotated.pdf copy'); xref, page, color, and opacity are left entirely unexplained.

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 ('Change ONE existing highlight'), and the qualifiers 'ONE' and 'existing' implicitly separate this from the create-oriented apply_highlight and the propose_* siblings. It stops short of naming an alternative outright, so it is clear but not maximally differentiating.

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 precondition for use ('after explicit user approval') plus setup requirements, a fresh fingerprint and an existing *-annotated.pdf copy. It does not explicitly route the agent to propose_annotation_update versus apply_annotation_update, so guidance is strong but not complete.

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 does disclose meaningful behavior: a precondition that the output must not exist, an overwrite path that permits input and output to be the same annotated PDF, and a human-review gate. It still doesn't say what happens on a fingerprint mismatch or what the call returns, which are notable gaps for a mutation 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?

Three short sentences, each doing work, with the core action front-loaded and the constraints following. No filler or restatement of the tool name. Slightly dense phrasing but appropriately sized.

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, no annotations, and 5 required parameters, the description covers the safety and workflow essentials but leaves key operational questions unanswered: how the fingerprint is verified/mismatch handling, and the meanings of the required quote/page params. Adequate for the happy path, incomplete for correct invocation in edge cases.

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% across 9 parameters, so the description must compensate but largely doesn't. It touches only expected_fingerprint (the 'checked' fingerprint), file/output_file, and overwrite_annotated_copy; page, exact_quote, color, opacity, and occurrence are left entirely undocumented in both schema and prose.

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: applying a proposed exact-match highlight with a verified source fingerprint. This clearly differentiates it from the propose_* siblings (proposal step) and the apply_annotation_* siblings (updates/removals), even though it never names the sibling it pairs with. 'Exact-match' and 'checked source fingerprint' are concrete scoping details an agent can act on.

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 states two explicit usage constraints: the output must not already exist, and the tool must not be called without showing the proposal to the user first. The overwrite_annotated_copy case is described for subsequent updates. What's missing is an explicit pointer to propose_highlight as the required preceding step, so the workflow is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only operation and discloses that colors and object references are returned, but it does not cover permissions, pagination, or whether the result spans all pages when page is omitted.

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 wasted words. It efficiently conveys the core purpose and output details.

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 read-only list tool with no output schema or annotations, the description covers the basic purpose and some return content. However, it omits scope behavior for the optional page parameter, leaving a meaningful gap for callers.

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%, and the description does not explain the 'file' or 'page' parameters. While the parameter names are relatively intuitive, the description adds no meaning beyond the schema and fails to clarify the optional page filter.

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 ('existing PDF annotations'), and adds output detail ('stored colors and object references'). This clearly distinguishes it from sibling tools like apply_highlight, read_pdf_page, and propose_annotation_update.

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 guidance on when to use this tool versus alternatives such as read_pdf_page or list_pdfs. The description also omits any mention of the optional page parameter or when to omit 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 provided, the description carries the full behavioral burden. It usefully discloses a hard cap ('up to 200'), which signals possible truncation, but omits whether listing recurses into subdirectories, what order results come in, or what happens when the workspace holds more than 200 files.

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 tight sentence with the resource and scope front-loaded and the result cap appended. No filler or redundancy; 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?

For a zero-parameter listing tool with no output schema and no annotations, the description covers the essentials (what is listed, from where, and the cap). It stops short of describing the return shape (names vs. paths) or the behavior past the 200-file limit, but the low tool complexity makes this nearly 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-arg tool applies. The description appropriately adds no invented parameter detail.

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 ('List') and resource ('PDF files') scoped to a 'configured local workspace,' which is unambiguous. It is inherently distinguishable from siblings like read_pdf_page, render_pdf_page, and list_annotations, which operate on page contents or annotations rather than enumerated files.

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 statement of when to use this tool versus alternatives, nor any prerequisites (e.g., whether a workspace must be pre-configured). The intended discovery role is only inferable from the name and the sibling set, so guidance is essentially absent.

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 the key trait: the PDF is not modified. That is a meaningful behavioral claim. It does not say what the preview returns, whether the proposal is persisted or handed to apply_annotation_removal, or how errors on a missing xref are surfaced.

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 sentence with no filler; the preview semantics and the non-mutation guarantee are both front-loaded where an agent will read them first.

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, so return-value explanation is not strictly required, and the non-destructive intent is clear. But with undocumented parameters and no annotation coverage, the definition leaves the agent guessing how to obtain a valid xref and what the preview actually produces.

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

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

All three parameters (file, page, xref) have 0% schema description coverage, so the description must compensate and it does not. 'ONE existing highlight' hints that a single annotation is targeted, but nothing explains that xref is the annotation reference, how it is obtained (e.g., from list_annotations), or the page/file conventions.

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?

Specific verb ('Preview removal') plus a tightly scoped resource ('ONE existing highlight'), and the modifier 'without modifying the PDF' implicitly contrasts it with the apply-side siblings. It stops short of naming apply_annotation_removal directly, so sibling routing relies on inference from the propose/apply naming pattern.

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?

'Preview' implies the dry-run-before-apply workflow, which is adequate context for the propose/apply pair. However, it never states when to use this instead of apply_annotation_removal, nor any prerequisite (e.g., that a preview should precede the mutation).

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 burden, and it clearly discloses the key safety trait: this is a preview that makes no changes. It does not describe what the proposal artifact contains or whether it expires/is tied to a later apply, so the disclosure is good but not exhaustive.

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

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

Two short sentences with zero filler; the scope constraint and the no-edit guarantee are front-loaded. Every clause earns its place.

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

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

For a 5-parameter tool with no annotations, no output schema and 0% schema coverage, the description covers intent, a key parameter source and the non-destructive behavior, but says nothing about the returned proposal or how it links to the subsequent apply call. 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 description coverage is 0% for 5 parameters, so the description must compensate. It specifies the two mutable fields (color, opacity) and points the agent at list_annotations as the source of page and xref, but file semantics are left entirely to the schema and no format hints (color encoding, opacity range) are given.

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 ("Preview changing"), a scoped resource ("ONE existing highlight") and the exact fields involved (color or opacity), with "no edits" explicitly separating it from the apply_annotation_update sibling. An agent can distinguish this from apply_annotation_update and propose_highlight 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?

Gives a concrete prerequisite ("Obtain page and xref from list_annotations") and an ordering instruction ("Review the proposed edit first"), which effectively frames the propose-then-apply workflow. It does not name apply_annotation_update as the follow-up tool, so the alternative is implied rather than stated.

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

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

With no annotations, the description carries the full burden; it does disclose the two most important behaviors: the search is normalization-aware and it performs no PDF mutation (read-only). It does not disclose failure behavior when no match is found, nor what a successful 'proposal' actually is, which matters for a propose/apply tool pair.

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, zero filler, with the read-only constraint front-loaded and the edge-case rule second. Nothing could be removed without losing 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?

For a 4-parameter tool with no annotations and no output schema, the description covers the mutation-safety question and the key parameter semantics, but omits the return shape ('locations' is vague) and the relationship to apply_highlight, leaving the propose/apply lifecycle incomplete.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for the non-obvious parameters: 'exact normalized words' clarifies exact_quote's matching semantics and the '1-based occurrence' rule clarifies occurrence's conditional purpose. file and page remain undocumented, but they are self-evident.

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 ('exact normalized words'), and its locations, plus a clear scope qualifier ('WITHOUT modifying any PDF'). This distinguishes it in spirit from apply_highlight, but the sibling is never named, so an agent must infer the propose/apply split from naming convention alone.

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

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

It gives a conditional rule for the repeated-passage case ('specify 1-based occurrence explicitly'), which is genuine usage guidance. However it never says when to prefer this over apply_highlight or that the result is meant to feed a subsequent apply step, so the workflow context 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 it does add real context: page numbering is 1-based and the returned data includes a SHA-256 document fingerprint. It omits what happens on pages without selectable text (e.g., scanned PDFs) and gives no error or pagination behavior, leaving notable gaps.

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 tight sentence with no padding, front-loading the core action. Efficient, though the fingerprint tail could arguably be trimmed since there is no output schema to explain return values.

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 read tool with no output schema, the description covers the essentials (text extraction, 1-based indexing, fingerprint). It still lacks file-format guidance and scanned-PDF limitations that an agent would need to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that 'page' is 1-based, which is genuinely useful, but says nothing about the required 'file' parameter (path vs. id, accepted formats), so half the parameters remain unexplained.

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 ('Read') and resource ('selectable text from a 1-based PDF page'), which distinguishes it from the rendering sibling by emphasizing text extraction rather than image output. However, it never names render_pdf_page or any alternative, so the distinction is only implicit.

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-to-use guidance. The phrase 'selectable text' hints that image-only/scanned pages are out of scope, but the agent is left to infer this and gets no routing help against render_pdf_page.

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 discloses that annotations are baked into the render and that output is a local PNG, but says nothing about where the file is written, whether it overwrites, or how the caller retrieves it — significant gaps for a tool that writes to disk.

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 tight sentence with the action front-loaded and no filler. Every clause (render, PDF page, annotations, local PNG, visual review) adds 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?

With no annotations, no output schema, and no parameter descriptions, the definition leaves the agent unable to determine the output artifact's location or how to consume it. For a tool whose whole purpose is producing a file, that is a material omission.

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. It only implies a page is rendered and never clarifies the 'file' parameter (path? identifier?) or the 'page' parameter's 1-based indexing and default. No added meaning beyond the raw 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?

Specific verb+resource+output: renders a PDF page to a local PNG. The parenthetical '(including annotations)' and the phrase 'visual review' differentiate it implicitly from text-oriented siblings like read_pdf_page and list_pdfs, though no sibling is named.

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?

'for visual review' implies when to reach for this rather than read_pdf_page, but there is no explicit when-to-use statement, no prerequisites, and no named alternative. Usage is inferable rather than stated.

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