Fix: Tell callers to omit notify and keep the default recipients

[shane-tw]

The trap

notify is a single value on the wire — true, "ALL", or a comma-separated ID list. There is no additive shape, so a supplied value replaces the default recipients rather than widening them. Asked to comment and let one person know, a client sets notify to that person alone and every follower the default would have notified is dropped.

Nothing reveals it. The response carries no recipient list, projects.Comment has no follower field, and no read path returns one — so the call succeeds identically either way and the mistake is never learnt.

The description advertised the accepted shapes and said nothing about the cost of using one, which reads as an invitation to fill the parameter in.

The change

helpers.NotifySchema now opens by telling the caller to omit it, and names the default it would be replacing:

Who to notify of the new comment. Omit it unless the user named who to notify: the default notifies every follower of the related entity, and a value here replaces that set rather than adding to it, so a narrower one silently drops everyone else who would have been told. Accepts the string "all" …

The wording follows the parameter's existing split: every follower of the related entity for comments, all project members for messages, replies and links — all 8 call sites, since the same trap applies to each.

Omitting the parameter is not the same as omitting the field, which is what makes the advice safe to give: the handlers substitute their own default (1f7c708), where the endpoints left to themselves notify nobody.

Notes

• TestNotifySchema pins both branches — the advice, the default it names, and that every shape parseNotify coerces is still advertised.
• Cost: +374 tokens, +0.57% of the tool-definitions block (go run ./cmd/mcp-tokens -base=main), spread over 8 tools.
• Generated docs are unchanged — they carry tool descriptions, not parameter descriptions.

🤖 Generated with Claude Code