changedetection_update_watch

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

Annotations already declare non-read-only but idempotent and non-destructive, so the safety profile is covered; the description adds the confirm/dry-run gate, which is valuable. However, it never says whether the update is a partial patch or a full replace, what happens to omitted fields, or whether permissions/auth are needed. For a 56-field mutation that ambiguity is material.

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 tight fragments, zero filler, with the purpose front-loaded before the endpoint and field hints. The brevity is appropriate stylistically, though it is achieved partly by offloading information elsewhere rather than by efficient compression.

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?

Given 56 parameters, nested objects, low schema coverage, and no output schema, this description is far too thin. An agent cannot determine update semantics, which fields are required for a valid PUT, or what a successful response looks like without consulting another tool or the full spec.

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 only 29%, so the description needs to compensate, but it delegates almost everything to "same writable fields as create, plus last_viewed." That forces the agent to open changedetection_create_watch to understand the 55 non-uuid fields, and it still leaves partial-vs-full semantics unresolved. The only field-level addition is the last_viewed note, which is already documented in 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 resource ("Update a watch") and anchors it to an existing resource via the required uuid and the PUT endpoint. It also distinguishes itself from create by saying the writable fields are the same as create, plus last_viewed. It does not, however, distinguish itself from setter siblings such as set_watch_state or set_watch_muted that also mutate a watch.

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 only explicit usage guidance is "Omit confirm for a dry-run," which is a useful call pattern for a destructive-ish mutation. There is no statement of when to prefer this over update_tag, set_watch_state, set_watch_muted, or create_watch. Usage is implied by the verb 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.