---
id: 10545
title: Tighten wakeSuppressed description in add_message MCP tool
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees: []
createdAt: '2026-04-30T22:50:55Z'
updatedAt: '2026-05-01T08:17:03Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10545'
author: neo-opus-ada
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-01T08:17:03Z'
---
# Tighten wakeSuppressed description in add_message MCP tool

## Context

Surfaces from Discussion [#10542](https://github.com/neomjs/neo/discussions/10542) and a recurring misuse pattern observed live in this session. @tobiu flagged the root cause: *"maybe the tool description for wakeSupression is unsufficient. if you work without me, you idle out and never get the message."*

The current `wakeSuppressed` parameter description on `add_message` (in `ai/mcp/server/memory-core/openapi.yaml`) hints at the use case but does not constrain misuse. Empirical anchor from this session: @neo-gpt incorrectly used `wakeSuppressed: true` on two active cross-family coordination messages about #10542 (`MESSAGE:7bd9a915` v2 direction + `MESSAGE:61a043cf` boundary refinement). Result: no wake events fired, I posted my follow-up at 22:34Z blind to GPT's v2 direction posted ~7 min earlier. @tobiu had to manually flag the inbox via chat to surface the missed messages. GPT acknowledged misuse and articulated the correct operational invariant in `MESSAGE:d3c1900d`. The tool description is the layer where this invariant should be codified to prevent recurrence across all agents.

## The Problem

**Current description** (verified in `ai/mcp/server/memory-core/openapi.yaml`):

> *"Persist the message without emitting SENT_TO_ME wake events. Use for mailbox-only session-sunset handovers that the next boot should read without re-entering the active sender harness."*

What it does:
- Names the use case (sunset handovers) ✓
- Explains the wake-event mechanism ✓

What it MISSES:
- No anti-pattern callout — agents reading "no action requested" / "observer FYI" reasonably (but incorrectly) infer `wakeSuppressed` is the right way to express "don't wake the recipient"
- No consequence framing — fails to communicate that misuse causes silent message loss in autonomous swarm mode
- No explicit constraint — "Use for X" reads as a hint, not a restriction

**Failure mode in autonomous swarm mode (per @tobiu):** when humans aren't polling the substrate (sleeping / off-hours), `wakeSuppressed: true` messages are silently invisible to the recipient until their next session boot. This breaks night-shift continuity (the very scenario Discussion #10542 is designing for) and cross-family coordination loops.

## The Architectural Reality

- **Owning file:** `ai/mcp/server/memory-core/openapi.yaml`
- **Tool:** `add_message` (POST `/mailbox/messages`)
- **Parameter:** `wakeSuppressed` (boolean, default `false`)
- **Consumer:** every agent calling `add_message` reads the description at tool-shape enumeration time. The description IS the operational guidance for when to set `true` vs `false`.

The fix layer is the description text itself — schema-level validation can't easily distinguish appropriate uses (sunset self-DMs) from inappropriate ones (active coordination), so description discipline is the right enforcement mechanism. Per pr-review-guide.md §5.3 MCP-Tool-Description Budget Audit, descriptions should be terse but content-justified — multi-clause framing IS acceptable when the constraint genuinely requires it.

## The Fix

Replace the current description with a constraint-shaped revision that:

1. States the strict use case
2. Names anti-pattern uses explicitly
3. Names the autonomous-mode consequence

**Proposed revision** (~50 words, content-justified per pr-review §5.3):

```yaml
wakeSuppressed:
  type: boolean
  default: false
  description: "Persist the message without emitting SENT_TO_ME wake events. STRICT: only for mailbox-only session-sunset handovers (self-DMs the next session reads at boot). DO NOT use for 'observer/FYI', coordination threads, status updates, or acknowledgments — those must still wake recipients. In autonomous swarm mode, wakeSuppressed: true messages are silently invisible until the recipient's next boot. Default: omit (= false)."
```

Same parameter, same schema, sharper operational constraint.

## Acceptance Criteria

- [ ] **(AC1)** `wakeSuppressed` description in `ai/mcp/server/memory-core/openapi.yaml` updated with explicit STRICT-constraint framing.
- [ ] **(AC2)** Description names anti-pattern uses ("observer/FYI", coordination threads, status updates, acknowledgments) explicitly.
- [ ] **(AC3)** Description names autonomous-mode consequence (silent invisibility until recipient's next boot).
- [ ] **(AC4)** Description budget-compliant per `pr-review-guide.md` §5.3 — content-justified multi-clause framing is acceptable; verify no internal cross-refs / phase numbering / session IDs leaked into the description.
- [ ] **(AC5)** Live MCP server `tools/list` probe confirms updated description surfaces correctly. Empirical command: `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node ai/mcp/server/memory-core/mcp-server.mjs`
- [ ] **(AC6)** Existing tests at `test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs` continue to pass.
- [ ] **(AC7, post-merge)** No recurrence of misuse pattern in subsequent A2A traffic over the next 14 days. Tracked via mailbox audit: count of `wakeSuppressed: true` messages whose subject does NOT contain "sunset" / "handover" / "boot pickup" — should trend toward zero post-merge.

## Out of Scope

- **Schema-level validation rejecting misuse.** The description discipline is the right layer; schema can't distinguish appropriate from inappropriate uses without semantic context.
- **Updating other MCP tool descriptions broadly.** Reviewer-side audit per `pr-review-guide.md` §5.3 covers ongoing description-budget discipline; this ticket targets one specific parameter with empirical misuse evidence.
- **Bundling with PR #10544** (Phase 0+2 session-sunset combined PR). Different substrate (OpenAPI YAML vs skill body); different concern. Per `quality-over-speed` discipline + scope hygiene.
- **Adding bridge-daemon-side enforcement** to drop `wakeSuppressed: true` messages that don't match sunset handover taxonomy. Possible follow-up if description discipline proves insufficient.

## Avoided Traps

- **Trap: bundle with #10544.** Rejected — different file, different scope. PR #10544 modifies `.agents/skills/session-sunset/references/session-sunset-workflow.md`; this ticket modifies `ai/mcp/server/memory-core/openapi.yaml`. Different reviewers, different change-class, different blast radius.
- **Trap: build validation-layer rejection.** Rejected per Out of Scope — schema-level rejection without semantic context is unsafe.
- **Trap: rewrite all MCP tool descriptions broadly.** Rejected per `feedback_audit_subsystem_guides_before_architectural_claims.md` discipline — this ticket is narrowly evidence-driven; broader audit is reviewer-side ongoing work.
- **Trap: weaken to "should" / "recommended" language.** Rejected — empirical anchor (this session's misuse twice within ~10 minutes) shows hint-shape language is insufficient. Need constraint-shape framing.
- **Trap: include implementation-internal cross-refs in description.** Rejected per pr-review §5.3 — description budget should stay usage-focused, not cite ticket numbers / Phase sequencing / session IDs.

## Related

- **Origin discussion:** [#10542](https://github.com/neomjs/neo/discussions/10542) — broader sunset-substrate work where the misuse pattern surfaced
- **Phase 0+2 sibling PR:** [#10544](https://github.com/neomjs/neo/pull/10544) — adjacent substrate scope (session-sunset skill body); does NOT bundle
- **Substrate predecessor:** [#10498](https://github.com/neomjs/neo/issues/10498) (CLOSED) — added the `wakeSuppressed` parameter for sunset self-DM purposes; this ticket tightens its description
- **Architectural reference:** `pr-review-guide.md` §5.3 MCP-Tool-Description Budget Audit (description-discipline framework)
- **Empirical anchors:** `MESSAGE:7bd9a915` + `MESSAGE:61a043cf` (the misuse instances), `MESSAGE:d3c1900d` (GPT's self-correction with operational invariant)

Origin Session ID: d0ec90a4-9a99-4fd7-baf6-dc0ab35e77dd

Retrieval Hint: `query_raw_memories(query="wakeSuppressed misuse autonomous swarm coordination silent loss tool description tightening #10542")`

## Timeline

- 2026-04-30T22:50:56Z @neo-opus-ada added the `documentation` label
- 2026-04-30T22:50:56Z @neo-opus-ada added the `enhancement` label
- 2026-04-30T22:50:56Z @neo-opus-ada added the `ai` label
- 2026-04-30T22:52:44Z @neo-opus-ada cross-referenced by PR #10544
- 2026-05-01T08:02:34Z @neo-gemini-pro cross-referenced by PR #10554
- 2026-05-01T08:12:37Z @neo-gemini-pro referenced in commit `0bb191f` - "docs(mcp): tighten wakeSuppressed description in memory-core (#10545)"
- 2026-05-01T08:17:03Z @tobiu referenced in commit `1e4687a` - "docs(mcp): tighten wakeSuppressed description in memory-core (#10545) (#10554)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-01T08:17:03Z @tobiu closed this issue
- 2026-05-05T16:44:45Z @neo-opus-ada cross-referenced by #10757

