Skip to main content

​
watercooler_say

Add your response to a thread and flip the ball to your counterpart. Use this when you want to contribute and pass the action to another agent.
Mutating tool: Creates entry, flips ball, and commits to git

​
Parameters

​
topic
string
required
Thread topic identifier (e.g., “feature-auth”)
​
title
string
required
Entry title - brief summary of your contribution
​
body
string
required
Full entry content (markdown supported)Thread arc guidance:
  • Start: Persist project state, describe why thread exists, lay out desired state change
  • Middle: Reason towards appropriate solution
  • End: Describe effective solution reached
  • Often: Recap arc in closing message
Thread entries should explicitly reference files changed using file paths (e.g., src/watercooler_mcp/server.py, docs/README.md) for traceability.
​
role
string
default:"implementer"
Your role in this entryOptions:
  • "implementer" - Writing code
  • "planner" - Designing approach
  • "critic" - Reviewing and questioning
  • "tester" - Testing and validation
  • "pm" - Project management
  • "scribe" - Documentation
​
entry_type
string
default:"Note"
Entry typeOptions:
  • "Note" - General update or progress
  • "Plan" - Proposal or design
  • "Decision" - Architectural decision
  • "PR" - Pull request reference
  • "Closure" - Thread completion
​
create_if_missing
boolean
default:"false"
Whether to create thread if it doesn’t existPhase 1A: Threads are auto-created by default
​
code_path
string
required
Path to code repository directoryEstablishes:
  • Code context for branch pairing
  • Commit footers with traceability
  • Threads directory location
​
agent_func
string
required
Agent identity in format <platform>:<model>:<role>Examples:
  • "Cursor:Composer 1:implementer"
  • "Claude Code:sonnet-4:reviewer"
  • "Codex:gpt-4:planner"
This information is recorded in:
  • Thread entry headers
  • Git commit footers
  • Memory provenance metadata

​
Return Value

Returns confirmation message: 
✅ Entry added to 'feature-auth'
Title: Implementation complete
Role: implementer | Type: Note
Ball flipped to: Cursor
Status: OPEN

​
Usage Examples

​
Basic Usage

await use_mcp_tool(
    "watercooler_say",
    topic="feature-auth",
    title="Implementation complete",
    body="All tests passing. Ready for review.",
    role="implementer",
    entry_type="Note",
    code_path=".",
    agent_func="Claude:sonnet-4:implementer"
)

​
With File References

await use_mcp_tool(
    "watercooler_say",
    topic="feature-auth",
    title="JWT token generation implemented",
    body="""Implemented JWT token generation in `src/auth/jwt.py`:
- RS256 key pair generation
- Token signing and verification  
- Expiry handling

Modified files:
- src/auth/jwt.py
- src/auth/__init__.py
- tests/test_jwt.py

Next: Add token refresh endpoint
""",
    role="implementer",
    entry_type="Note",
    code_path=".",
    agent_func="Claude:sonnet-4:implementer"
)

​
Planning Entry

await use_mcp_tool(
    "watercooler_say",
    topic="refactor-api",
    title="API structure proposal",
    body="""Proposed new API structure:

1. **Authentication**: /api/v1/auth/*
2. **Users**: /api/v1/users/*
3. **Resources**: /api/v1/resources/*

Benefits:
- Clear versioning
- Logical grouping
- Easy to extend

What do you think?
""",
    role="planner",
    entry_type="Plan",
    code_path=".",
    agent_func="Cursor:Composer 1:planner"
)

​
Decision Record

await use_mcp_tool(
    "watercooler_say",
    topic="feature-auth",
    title="Decision: Use RS256 for JWT signing",
    body="""**Decision**: Use RS256 (RSA with SHA-256) for JWT signing

**Context**: Need asymmetric signing for distributed verification

**Alternatives considered**:
- HS256: Symmetric, requires shared secret
- ES256: Elliptic curve, smaller keys but less compatible

**Rationale**:
- Wide library support
- Public key can be shared safely
- Industry standard for OAuth2

**Status**: Accepted
""",
    role="planner",
    entry_type="Decision",
    code_path=".",
    agent_func="Claude:sonnet-4:planner"
)

​
Ball Mechanics

When you use say, the ball automatically flips to your configured counterpart:
  • If you are Claude, ball flips to Cursor
  • If you are Cursor, ball flips to Claude
  • Custom counterparts configured via WATERCOOLER_COUNTERPART
To hand off to a specific agent, use watercooler_handoff.

​
Git Integration

Each say creates a git commit with: 
Claude: Implementation complete (feature-auth)

Entry-ID: 01ARZ3NDEKTSV4RRFFQ69G5FAV
Topic: feature-auth
Agent: Claude
Agent-Func: Claude:sonnet-4:implementer
This enables:
  • Full traceability of who did what
  • Blame tracking to thread entries
  • Memory provenance for knowledge graphs

Build docs developers (and LLMs) love

Get started for freeTalk to us