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

Goes well beyond the annotations: it discloses the permission model, the self-removal exception, the notification/side effects of becoming a collaborator, how unresolvable references are surfaced in `warnings`, the full enum of `skipped` reasons, and the return payload. The destructiveHint is contextualized by showing exactly what removal does and what it does not do.

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 purpose and role definition, then permissions and return value. It is dense and long, but each sentence carries distinct information; the skip-reason enum could arguably be trimmed since such reasons are also discoverable at runtime.

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?

No output schema exists, so the description correctly states the return value ('the task's collaborators after the change'), and it covers permissions, ambiguity handling, dry-run behavior, and failure modes. An agent has everything needed to invoke 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 coverage is 100% so the baseline is 3, but the description adds real meaning: `add`/`remove` accept user id, full name, first name, or email, and an ambiguous reference is dropped and reported rather than erroring. It also clarifies dryRun semantics ('resolve the people and check the permission, write nothing'), which the schema only summarizes.

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+resource (add/remove collaborators on one task) and immediately scopes it against the sibling concept of a single assignee, so an agent can distinguish it from assign_task without opening the schema. The role semantics (sees in My Work, notified, may update, cannot reassign) are unambiguous.

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 clear conditions for use: requires task.assign plus task.edit.any or task ownership, with an explicit exception that anyone may remove themselves, and implies the assignee is never a collaborator. It does not explicitly name an alternative tool (e.g. assign_task for changing the assignee) or state when not to use it, 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.