Remove work package watcher

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

The description goes far beyond annotations by disclosing critical behavioral nuances: the API returns 204 regardless of whether the user was actually watching, resulting in 'changed' being null; a 404 indicates an unknown user or work package, not non-membership; and the operation does not unassign or remove from project. These are exactly the kind of hidden behaviors agents need, and they complement the idempotentHint and destructiveHint annotations without contradiction.

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 longer than necessary but earns its length through crucial pitfalls and permission details. It is well-structured with a clear 'Pitfalls' section that is immediately relevant to safe execution. No sentence is wasted, though a more compressed format could have achieved the same impact.

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 subtle API behaviors, the description covers all essential context: operation, return value (though output schema exists), permission requirements, error semantics, and cross-references to related tools. The presence of an output schema does not detract; the description adds the non-obvious 'changed is null' detail that the output schema alone would not convey.

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 input schema already provides 100% coverage of both parameters, including how to obtain IDs and the rejection of 'me' for user_id. The description adds no new parameter-level meaning beyond what the schema states; it merely restates and contextualizes. Per the rubric, baseline 3 is appropriate when schema does the heavy lifting.

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 opens with a specific verb and resource: 'Unsubscribe a user from a work package's notifications.' This clearly distinguishes it from siblings like add_work_package_watcher and get_work_package, and the cross-reference to add_work_package_watcher as the reverse further cements its unique purpose.

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 explicitly states when to use this tool ('Use this to stop notifying someone who no longer needs the updates'), provides permission prerequisites (removing others requires delete-work-package-watchers permission, self-removal requires view access), and names alternatives (get_work_package with include=['watchers'] for listing current watchers, add_work_package_watcher as the reverse). This fully covers usage context and exclusions.

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