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

Annotations already declare the safety profile (not read-only, idempotent, non-destructive, closed-world), and the description adds behavior the annotations cannot express: auto-reopen on CISA KEV entry or reported exploitation, the 90-day snooze ceiling and that it reopens on expiry, and that PATCHED is confirmed by the next read. The org-scoping sentence ("Changes nothing outside the caller's organization") also bounds blast radius, which is exactly the kind of context the annotations leave out.

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 front-loaded sentence leads with verb and resource, then layers status meanings and edge behavior; nothing is filler. It is dense and parenthetical-heavy to the point of being a run-on, which costs a point on readability, but no sentence could be deleted 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?

With only three params, full schema coverage, no output schema and annotations covering safety, the description supplies the remaining load-bearing facts: status meanings, snooze limit, auto-reopen triggers, and org scope. Minor gaps remain (what error surfaces if snoozedUntil is omitted, whether a snooze can be shortened later), but an agent can call it correctly from this definition.

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 the baseline is 3; the description earns above baseline by giving each enum value a meaning beyond the schema's bare "The new status", and by restating the snooze constraint alongside the id format. The findingId and snoozedUntil semantics are largely duplicative of the schema text, which keeps it from a 5.

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 ("Set the status of one vulnerability-monitoring finding") and immediately enumerates the exact status values, so the agent knows precisely what the tool changes. It also names the origin of the finding id (watch_domain, watch_dependencies, Exposure page), which separates it from the sibling watch_* tools that create findings rather than act on 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?

Each status is glossed with the real-world condition that selects it ("PATCHED (upgraded; the next read confirms it)", "NOT_AFFECTED (e.g. a distro backport fixed it)"), which is genuine when-to-use guidance. It stops short of explicit exclusions — nothing says when not to ack, or what to do instead of snoozing indefinitely — so it is clear context rather than full routing.

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