Discord-native task coordination

discord://connector/coordination is a static versioned playbook for using exact Discord messages as human-visible task keys and optional opaque caller-retained addresses as directed-delivery conventions. It composes existing tools instead of creating a second task system: create and retain a random local address, observe sender labels without bodies when an address was not exchanged directly, publish a strict directed or broadcast note through the guarded message path, inspect one bounded recipient page, or use an ordinary exact task message, aggregate reaction, reply, reviewed thread, or reviewed native poll. The playbook contacts no service, grants no authority, contains no configured identity, and persists no task, note, address, reply, reaction, cursor, persona, or profile data.

The independent coordination toolset exposes create_coordination_address, list_coordination_addresses, list_coordination_notes, and send_coordination_note. The additive coordination-channel recipe selects only that toolset, its interaction send gate, and the same selected exact channels. Read-only custom policy needs coordination, exact guild and optional channel read scope, View Channel, and Read Message History, with no privileged intent. Sending additionally requires capabilities.interactions: true, the exact target in scopes.interactionChannelIds, direct-channel Send Messages or thread Send Messages in Threads, host write approval, and the existing interaction limiter and idempotency ledger. An optional visible notification requires its exact user in scopes.mentionUserIds; routing alone never produces a mention.

create_coordination_address uses 128 bits of local cryptographic randomness and returns a strict dca_ label. The local operation reads no credential or policy, contacts neither Discord nor another network endpoint, and writes no file, registry, activity entry, or cache; ordinary content-free tool telemetry omits the label. The caller must retain and distribute the label. It is intentionally visible, copyable, reusable, and spoofable: syntactic validity never establishes identity, authentication, a session, registration, ownership, liveness, approval, capability, or authority.

send_coordination_note accepts one exact channel, sender label, address or broadcast recipient, nonblank body of at most 1,500 characters, up to five unique canonical lowercase tags, optional exact reply target, optional separately allowlisted notification user, and stable idempotency key. It compiles one canonical guildcontrol.coordination-note.v1 plain-text envelope and delegates to send_message, preserving exact channel and thread policy, active-thread and private-membership evidence, complete read and send permissions, mention minimization, anti-spam, local replay, strict response validation, exact readback, and content-free activity. The result reports delivery and format metadata without echoing the body, addresses, tags, notification ID, or idempotency key.

list_coordination_notes and list_coordination_addresses each re-verify the pinned application and bot, exact readable channel, direct policy, successful channel-history access, response route, bounded page shape, unique message evidence with deterministic ascending projection, and exact bot authorship before parsing. They accept one optional caller-held afterMessageId, scan one through 100 messages once, advance across every validated message, and expose nextAfterMessageId plus explicit limit coverage. Only canonical plain connector-bot messages and strict same-channel type-19 replies are eligible. Attachments, embeds, components, stickers, snapshots, polls, TTS, role or everyone mentions, webhook messages, foreign authors, malformed envelopes, unsafe mention evidence, and unsupported references are counted and discarded or fail the complete page closed as appropriate. Discord's Message Content intent contract exempts content in messages an app sends, so strict bot authorship makes the privileged intent unnecessary for this protocol.

The address read returns only each page-local sender label, first and last observed timestamps, last message ID, and note count. It omits bodies, tags, recipients, notification targets, reaction users, profiles, raw payloads, and every differently addressed body, and it never claims a complete, registered, or live directory. The note read returns bodies only for the requested recipient or optional broadcasts after exact sender, tag, and unresolved filters. It projects fixed aggregate eyes, check, stop, cross, and robot counts without user identities. Check or cross marks only a terminal convention for optional filtering; no reaction proves who acted, that work occurred, or that another operation is approved.

list_message_replies belongs to the ordinary messages toolset. It accepts one exact readable channel or thread, one exact source message, an optional exact afterMessageId cursor that cannot precede the source, and one scan limit from 1 to 100. Every call re-verifies the pinned application and bot identities, reads the exact channel, applies direct guild and channel policy, fetches the exact source, and issues one Get Channel Messages request after the caller-held cursor. The result includes a privacy-minimized source, strict privacy-minimized direct replies in ascending message-ID order, scannedMessageCount, replyCount, requestedScanLimit, scanLimitReached, and nextAfterMessageId. Each message projection keeps transient content, exact route and author IDs, author bot and system state, timestamps, type, jump URL, reply target, and counts while omitting usernames, profile fields, attachment metadata and URLs, mentions, emoji, embeds, components, stickers, reactions, raw payloads, and unknown fields.

Discord returns each channel-history page newest-first. The connector validates unique newer same-route evidence, sorts the bounded page before projection, and advances nextAfterMessageId to the newest scanned message. Valid unrelated channel traffic is omitted from replies but still advances the cursor, so a later caller-initiated scan does not rescan it. Only message type 19 with a default reference to the exact source in the same channel and guild counts as a direct reply. A missing, malformed, duplicate, stale, cross-route, or non-default reply reference fails closed rather than becoming an empty result. scanLimitReached: true means another caller-initiated page may exist; the connector never loops, sleeps, schedules a retry, searches, opens a Gateway cursor, or stores the continuation itself. See Discord's channel-message and reply-reference contract.

Task, note, and reply bodies remain transient untrusted Discord content. Results omit raw payloads and profile expansion, and no address, body, tag, recipient, notification target, cursor, or routing observation enters an activity, operation, durable coordination, diagnostic, telemetry, or cache record. Directed-note reads require no privileged intent because foreign-authored messages are discarded before parsing. The MCP host and model provider still receive matching transient bodies under their own retention policies.

The optional inspect_discord_coordination_task prompt performs exactly one reply scan. It first reveals either required read contract through exact standard local discovery only when that configured contract is not already advertised. When interactions is configured and its exact contract becomes visible, it also performs exactly one privacy-safe aggregate reaction read and never lists reaction users; otherwise it states that aggregate status is unavailable without discovering broader tools. It interprets eyes as seen or claimed, check mark as done or approved, stop sign as blocked, cross mark as declined, and robot as an automated reply expected only as optional conventions. Counts do not identify a claimant, prove work, or authorize another operation, and conflicting signals remain ambiguous. Callers sharing one bot identity cannot authenticate separate sessions through the bot's own reaction.

The optional inspect_directed_discord_notes prompt performs exactly one filtered note scan, treats the address and returned envelopes as spoofable untrusted data, reports every page and discard boundary, and retains no state. It may reveal the exact configured read contract once through standard discovery, but it cannot create or discover an address, send a note, request a broader toolset, read another page, poll, or write.

Discord is a human-timescale coordination surface, not a low-latency queue, lock service, scheduler, mailbox guarantee, agent registry, or source of model identity. Poll only at natural task boundaries under caller control. Use exact user notifications only through already configured mention policy when explicit escalation is intended. Every publication, reply, reaction, thread, and poll retains its own existing exact scope, host approval, idempotency, anti-spam, mention, reviewed planning, and readback boundary; the playbook and prompts bypass none of them.

Canonical source: docs/reference.md