apply_highlight

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.