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 that both pending and resolved annotations are affected, which is real scope information, but omits irreversibility, permission requirements, and any returned count for what is clearly a bulk 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 front-loaded sentence with no filler; the destructive verb and full scope are communicated immediately.

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 tool with no output schema the surface area is small, but a destructive bulk delete with no annotations should still warn about irreversibility or confirm the effect. The description covers what is deleted but not what happens after.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description has no parameter semantics to add. Baseline 4 applies for a no-argument tool.

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 (Delete) and resource (all annotations), and the parenthetical 'pending and resolved' narrows scope precisely, distinguishing it from the single-annotation siblings. It does not name an alternative tool, but the 'all' scope makes the distinction from get_annotation/resolve_annotation obvious.

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, nor any mention of alternatives among the six siblings. The intent is inferable from the name, but the description adds nothing about preconditions or safer alternatives.

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 return payload ('full details and screenshot'), which is real value for a tool with no output schema, but says nothing about permissions, behavior when the id is not found, or whether the id is resolved against a live session.

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?

One sentence, front-loaded with the return content and the lookup key, with no padding or redundancy. 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 single-entity read with one fully documented parameter and no output schema, the description covers what the agent gets (details plus screenshot). It lacks only edge-case behavior such as unresolved or invalid ids, which is a minor gap rather than a blocking one.

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% and the single parameter is already documented as 'Annotation id (8 chars) or its pin number'. The description's 'by id or number' merely restates that, adding no syntax or format detail beyond the schema. Baseline 3 is correct.

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 ('full details and screenshot for a single annotation'), and the word 'single' plus 'by id or number' marks it off from list_annotations and get_pending_annotations. It stops short of naming any sibling explicitly, so it sits at a clear-but-undifferentiated 4.

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 gives no when-to-use guidance and never names an alternative among the six siblings. An agent must infer that this is the fetch-one path versus list_annotations or get_pending_annotations; nothing in the text selects between them.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the return shape (markdown task list containing comment, element details, and screenshot), which genuinely helps. It does not say whether the call is read-only, whether it mutates or consumes pending state, pagination limits, or auth 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 short sentences, front-loaded with the operation and payload, followed by the ordering directive. Nothing is wasted and there is no filler.

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

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

For a simple one-parameter read tool with no output schema, the description covers the operation, the payload contents, and the recommended call order. Only minor gaps remain, such as pagination or whether pending state is consumed, but these are not blocking for correct invocation.

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

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

Schema description coverage is 100% for the single `url` parameter, so the schema already explains the prefix-match filter. The description adds no parameter detail beyond that, making the 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 and resource ("Return every pending annotation") and even specifies the payload contents and format (comment + element details + screenshot, as a markdown task list). It partially distinguishes itself from siblings via the "pending" scope, but never names list_annotations or get_annotation, so an agent must infer the difference.

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?

"Use this first" gives an explicit ordering hint, which is useful workflow context. However, it never states when NOT to use this tool or which sibling to use instead (e.g. list_annotations for non-pending items), so the guidance remains implied rather than directive.

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

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

With no annotations, the description carries the full burden, but it does disclose two useful traits: results are condensed to one line per annotation and the default filter is pending-only. It omits ordering, pagination/limits, and permission requirements, which is a meaningful gap for a list tool with zero annotation coverage.

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 no filler, and the output-format fact is front-loaded before the default-scope fact. Every sentence 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 single-parameter list tool with no output schema, the minimum is covered (what it returns, default scope), but ordering, result limits, and the distinction from get_pending_annotations are left unaddressed. Adequate but with clear omissions.

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 documents the default value of the status parameter ('pending only'), which is the single most important semantic detail, but adds nothing about the resolved/all enum values or whether combining them is meaningful.

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 (listing annotations) and adds the output shape ('one-line summary per annotation'), so an agent knows it is a summarized list rather than a detail fetch. However, it does not differentiate itself from the sibling get_pending_annotations, which appears to overlap with this tool's default behavior.

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?

'Defaults to pending only' hints at scope but gives no explicit when-to-use, when-not-to-use, or alternative tool guidance. The presence of a near-identical sibling (get_pending_annotations) makes the absence of routing guidance a real gap.

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 to lean on, the description carries the load and does so fairly well: it discloses that this reaches into the developer's live browser right now, that it returns a diff plus a fresh crop relative to the original capture, and the meaning of gone/moved verdicts. It omits latency/timeout expectations and any failure modes beyond the verdict vocabulary.

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 a distinct job: the action and its output, the trigger conditions, and how to interpret the verdict. The scope constraint and the payoff are front-loaded; 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?

There is no output schema, so the description must cover return semantics — and it does, naming the diff, the fresh crop, and the gone/moved verdicts. Combined with the fully documented parameters, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both parameters (id, timeoutSeconds) are already documented with format and defaults. The description only implies the id targets an element and adds nothing about the timeout or id format, 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 — re-verify an annotation's element against the live page and report the diff — with a concrete output artifact (a fresh crop alongside the original). It is clearly distinct from siblings like get_annotation or resolve_annotation, which fetch or close annotations rather than re-validating them.

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 two explicit triggers: call before editing anything marked a while ago, and whenever an annotation flags itself as possibly stale. It also explains how to act on the verdict (gone/moved means the selector can't be trusted as-is), but never states when not to call it or which sibling to prefer for adjacent needs.

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 and does so well. It explains that the message appears on the pin, the developer answers in the browser, the annotation returns as pending with the conversation attached, it reaches wait_for_annotation and the Claude Code hook, and it is off the pending list until answered.

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

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

The description is front-loaded with the core action and immediate usage conditions. The extra lifecycle detail is useful rather than wasteful, and the final sentence cleanly routes the agent to the alternative 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?

The description covers the workflow, state transition, downstream notification path, and alternative tool, which is strong for a two-parameter tool with no annotations or output schema. The remaining gap is that the id parameter's meaning is only implied rather than explicitly stated.

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 message parameter is reinforced as the question shown to the developer, and the workflow implies that id refers to the annotation. However, the id parameter has no schema description and the tool description never explicitly defines it, so it does not fully compensate for the 50% 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?

The description states a specific action: asking the developer a question about an annotation instead of resolving it. It explicitly distinguishes this from resolve_annotation, so an agent can select it without opening the sibling schema.

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

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

It gives explicit when-to-use conditions: the request is ambiguous, or a decision is needed before changing code. It also gives an explicit when-not: never use this to report a finished change, because that is resolve_annotation.

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 does disclose the key behavioral trait: the note is rendered in the developer's browser next to their original note, making this a user-facing communication channel rather than internal bookkeeping. It does not state whether the annotation is removed from the pending set, whether the call is idempotent, or what permissions are needed.

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

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

Front-loaded with the action, then the mandatory-call directive, then the note-quality requirement with a concrete example. Every sentence is functional, though the required-note point is restated three times (REQUIRED, "not bookkeeping", example contrast), which is slightly 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?

For a mutation tool with no annotations and no output schema, the description covers the trigger, the side effect, and the required-parameter contract well enough to call it correctly. Post-call state (does the annotation leave the pending list?), idempotency, and failure behavior beyond "say so in the note" are left unaddressed.

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

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

Schema coverage is only 50% (the `id` parameter is undocumented in both places), so the description must compensate — and it does for `note`, adding requiredness, its audience, its display location, examples, and explicit anti-examples ("Done" or "Fixed" is not an answer). It adds nothing for `id`, but the gap is minor given how self-evident that parameter is.

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 — "Mark an annotation done after applying the change" — and is readily distinguishable from the read-oriented siblings (get_annotation, list_annotations, wait_for_annotation) and from clear_annotations. An agent knows exactly what state transition this performs without opening the schema.

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

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

"Always call this when you have made the change" gives an unambiguous trigger, and "If you could not do it, say that here instead" handles the negative case, which is unusually helpful. It does not explicitly name alternative siblings (e.g. recheck_annotation) or state ordering prerequisites, so it stops short of 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?

With no annotations provided, the description carries the full burden, and it does disclose two important traits: the call blocks with a timeout bound, and each new annotation is delivered to exactly one waiting agent so concurrent watchers never duplicate work. It does not say what happens on timeout (empty result vs error) or whether any auth/session is required.

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, front-loaded with the blocking behavior and followed immediately by the loop pattern and the concurrency guarantee. No filler; each sentence adds a distinct fact.

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 should say what a returned annotation looks like and what a timeout yields — it covers the former only implicitly ('Each new annotation is handed to...') and leaves timeout return behavior unstated. The core blocking semantics are otherwise well covered.

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 a single optional parameter whose schema already documents the bounds (1–600) and the 120-second default, giving 100% schema coverage. The description only alludes to it via '(or timeout)' and adds no format or override guidance beyond the schema, so the baseline 3 applies.

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

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

The description gives a precise verb and blocking semantics: 'Block until the developer adds a new annotation in the browser (or timeout).' The blocking, exactly-once delivery model cleanly separates it from the polling siblings (get_pending_annotations, list_annotations) without needing to name them.

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

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

It names the scenario it exists for — a live 'watch' loop ('wait → apply → resolve → wait') — which tells the agent when to reach for it. It stops short of explicitly contrasting with the non-blocking alternatives (get_pending_annotations, recheck_annotation), so the 'when not to use' side is left to inference.

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