feat: document Pararam message formatting

Author: ivolnistov

README.md

@@ -62,6 +62,14 @@ Send a message to a chat with optional reply and quote functionality.
 - `reply_to_message_id` (optional): Post number to reply to
 - `quote_text` (optional): Text to quote from the replied message (only used with `reply_to_message_id`)
 
+**Message formatting:**
+Pararam supports Markdown-like text, but does not support Markdown headings (`#`, `##`, `###`).
+Use `**bold**` section titles instead. Use colors as `[#RRGGBB](text)`;
+colored bullet example: `[#2E7D32](●)`. Keep tables simple because colors may not render inside
+table cells. Use `@all`, `@online`, `@admin`, and `@groups` only when the user explicitly asks
+for broad notification, and ask for explicit confirmation before sending such mentions.
+See [docs/PARARAM_FORMATTING.md](docs/PARARAM_FORMATTING.md) for the full syntax.
+
 **Examples:**
 ```python
 # Simple message

docs/PARARAM_FORMATTING.md

@@ -0,0 +1,60 @@
+# Pararam Message Formatting Reference
+
+Use this reference when composing text for `send_message` or `edit_post`.
+
+## Core Rules For Agents
+
+- Do not use Markdown headings (`#`, `##`, `###`). Pararam does not support them.
+- Use `**bold**` section titles instead of headings.
+- Prefer plain bullets or numbered lists for structure.
+- Keep tool descriptions concise; use the `pararam://formatting` MCP resource only when the task needs details.
+
+## Mentions
+
+- `@user` mentions a user.
+- `@@role` mentions a role.
+- `@all` mentions all users in the chat.
+- `@online` mentions online users.
+- `@admin` mentions all admins.
+- `@groups` mentions all roles.
+
+Use `@all`, `@online`, `@admin`, and `@groups` only when the user explicitly asks to notify everyone,
+online users, chat admins, or groups/roles. Prefer targeted user or role mentions otherwise.
+Before sending any message with `@all`, `@online`, `@admin`, or `@groups`, ask the user for explicit confirmation.
+
+## Hashtags And Alerts
+
+- `#example` creates a hashtag.
+- `#eta` creates a reminder.
+- `#shareedit` enables collaborative editing for the post.
+- `#snd_call`, `#snd_ok`, `#snd_fail`, and `#snd_silent` choose the notification sound.
+
+## Links, Tooltips, And Colors
+
+- Markdown-style link: `[label](https://example.com)`.
+- Tooltip: `[visible text](tooltip text)`.
+- Colored text: `[#RRGGBB](text)` or `[#red](text)`.
+- Colored bullet: `[#2E7D32](●)`.
+- Phone link: `[#tel](+7 952 67 47 180)`.
+
+## Quotes, Code, And Inline Code
+
+- One-line quote: `> quoted text`.
+- Inline code or inline monospace: `` `text` ``.
+- Multiline block or code fence: start a separate line with three backticks.
+- For syntax highlighting, use a language after the opening backticks, for example ` ```python `.
+
+## Tables
+
+Tables are supported with Markdown table syntax. Keep them simple.
+Colors may not render inside table cells, so do not rely on colored markers in tables.
+
+## Checkboxes And Spoilers
+
+- Empty checkbox: `[ ](task text)`.
+- Checked checkbox: `[x](task text)`.
+- Spoiler: `[#spoiler](hidden text)`.
+
+## Attach Long Text
+
+To send text as an attachment, start a line with `/paste filename`.

docs/TOOLS.md

@@ -131,6 +131,14 @@ Send a message to a chat.
 - `text` (str): Message text to send
 - `reply_to_message_id` (str, optional): Post number to reply to
 
+**Message Formatting:**
+Pararam supports Markdown-like text, but does not support Markdown headings (`#`, `##`, `###`).
+Use `**bold**` section titles instead. Use colors as `[#RRGGBB](text)`;
+colored bullet example: `[#2E7D32](●)`. Keep tables simple because colors may not render inside
+table cells. Use `@all`, `@online`, `@admin`, and `@groups` only when the user explicitly asks
+for broad notification, and ask for explicit confirmation before sending such mentions.
+See `docs/PARARAM_FORMATTING.md` for the full syntax.
+
 **Returns:**
 `ToolResponse[SendMessagePayload]` with payload containing:
 - `post_no`: ID of the sent message

packages/pararam-nexus-mcp/src/pararam_nexus_mcp/formatting.py

@@ -0,0 +1,74 @@
+"""Pararam message formatting guidance exposed to MCP clients."""
+
+PARARAM_FORMATTING_GUIDE = """Pararam message formatting:
+- Do not use Markdown headings (#, ##, ###); Pararam does not support them.
+- Use **bold** section titles, bullets, numbered lists, blockquotes (>), inline code, and code fences.
+- Use colors as [#RRGGBB](text); colored bullet example: [#2E7D32](●).
+- Keep tables simple; colors may not render inside table cells.
+- Use @all, @online, @admin, and @groups only when the user explicitly asks to notify everyone,
+  online users, chat admins, or groups/roles.
+- Before sending a message with @all, @online, @admin, or @groups, ask the user for explicit confirmation.
+- For full syntax details, read the pararam://formatting resource.
+"""
+
+PARARAM_FORMATTING_REFERENCE = """# Pararam Message Formatting Reference
+
+Use this reference when composing text for send_message or edit_post.
+
+## Core Rules For Agents
+
+- Do not use Markdown headings (#, ##, ###). Pararam does not support them.
+- Use **bold** section titles instead of headings.
+- Prefer plain bullets or numbered lists for structure.
+- Keep tool descriptions concise; use this reference only when the task needs formatting details.
+
+## Mentions
+
+- @user mentions a user.
+- @@role mentions a role.
+- @all mentions all users in the chat.
+- @online mentions online users.
+- @admin mentions all admins.
+- @groups mentions all roles.
+
+Use @all, @online, @admin, and @groups only when the user explicitly asks to notify everyone,
+online users, chat admins, or groups/roles. Prefer targeted user or role mentions otherwise.
+Before sending any message with @all, @online, @admin, or @groups, ask the user for explicit confirmation.
+
+## Hashtags And Alerts
+
+- #example creates a hashtag.
+- #eta creates a reminder.
+- #shareedit enables collaborative editing for the post.
+- #snd_call, #snd_ok, #snd_fail, and #snd_silent choose the notification sound.
+
+## Links, Tooltips, And Colors
+
+- Markdown-style link: [label](https://example.com).
+- Tooltip: [visible text](tooltip text).
+- Colored text: [#RRGGBB](text) or [#red](text).
+- Colored bullet: [#2E7D32](●).
+- Phone link: [#tel](+7 952 67 47 180).
+
+## Quotes, Code, And Inline Code
+
+- One-line quote: > quoted text.
+- Inline code or inline monospace: `text`.
+- Multiline block or code fence: start a separate line with three backticks.
+- For syntax highlighting, use a language after the opening backticks, for example ```python.
+
+## Tables
+
+Tables are supported with Markdown table syntax. Keep them simple.
+Colors may not render inside table cells, so do not rely on colored markers in tables.
+
+## Checkboxes And Spoilers
+
+- Empty checkbox: [ ](task text).
+- Checked checkbox: [x](task text).
+- Spoiler: [#spoiler](hidden text).
+
+## Attach Long Text
+
+To send text as an attachment, start a line with /paste filename.
+"""

packages/pararam-nexus-mcp/src/pararam_nexus_mcp/server.py

@@ -11,6 +11,7 @@
 from fastmcp import FastMCP
 
 from pararam_nexus_mcp.config import config
+from pararam_nexus_mcp.formatting import PARARAM_FORMATTING_GUIDE, PARARAM_FORMATTING_REFERENCE
 from pararam_nexus_mcp.tools.chats import register_chat_tools
 from pararam_nexus_mcp.tools.posts import register_post_tools
 from pararam_nexus_mcp.tools.users import register_user_tools
@@ -44,10 +45,22 @@
 # Initialize FastMCP server
 mcp = FastMCP(
     name=config.mcp_server_name,
-    instructions=config.mcp_server_instructions,
+    instructions=f'{config.mcp_server_instructions}\n\n{PARARAM_FORMATTING_GUIDE}',
 )
 
 
+@mcp.resource(
+    'pararam://formatting',
+    name='pararam_message_formatting',
+    title='Pararam Message Formatting',
+    description='Full Pararam message formatting reference for composing send_message and edit_post text.',
+    mime_type='text/markdown',
+)
+def pararam_message_formatting() -> str:
+    """Return the full Pararam message formatting reference."""
+    return PARARAM_FORMATTING_REFERENCE
+
+
 async def _prune_to_limited_tools(server: FastMCP[None]) -> list[str]:
     """In limited mode, drop every registered tool not in the allow-list.
 

packages/pararam-nexus-mcp/src/pararam_nexus_mcp/tools/posts.py

@@ -494,6 +494,13 @@ async def send_message(
         """
         Send a message to a chat.
 
+        Message formatting: Pararam supports Markdown-like text, but not Markdown headings.
+        Use **bold** section titles instead. Use colors as [#RRGGBB](text);
+        colored bullet example: [#2E7D32](●). Keep tables simple because colors
+        may not render inside table cells. Use @all, @online, @admin, and @groups
+        only when the user explicitly asks for broad notification; ask for explicit
+        confirmation before sending such mentions. See pararam://formatting for full syntax.
+
         Args:
             chat_id: ID of the chat to send message to
             text: Message text to send
@@ -1619,6 +1626,13 @@ async def edit_post(
     ) -> ToolResponse[EditPostPayload | None]:
         """Edit an existing post.
 
+        Message formatting: Pararam supports Markdown-like text, but not Markdown headings.
+        Use **bold** section titles instead. Use colors as [#RRGGBB](text);
+        colored bullet example: [#2E7D32](●). Keep tables simple because colors
+        may not render inside table cells. Use @all, @online, @admin, and @groups
+        only when the user explicitly asks for broad notification; ask for explicit
+        confirmation before sending such mentions. See pararam://formatting for full syntax.
+
         Args:
             chat_id: Numeric chat ID.
             post_no: Post number to edit (must be authored by the token's user).

packages/pararam-nexus-mcp/tests/test_server.py

@@ -1,9 +1,21 @@
 """Tests for server module."""
 
 from pararam_nexus_mcp import __version__
+from pararam_nexus_mcp.formatting import PARARAM_FORMATTING_GUIDE, PARARAM_FORMATTING_REFERENCE
 
 
 def test_version() -> None:
     """Test that version is set."""
     assert isinstance(__version__, str)
     assert len(__version__) > 0
+
+
+def test_pararam_formatting_guide_mentions_supported_markup() -> None:
+    """Test that the MCP guidance documents Pararam-specific formatting."""
+    assert 'Markdown headings' in PARARAM_FORMATTING_GUIDE
+    assert '**bold**' in PARARAM_FORMATTING_GUIDE
+    assert '[#2E7D32](●)' in PARARAM_FORMATTING_GUIDE
+    assert '@all' in PARARAM_FORMATTING_GUIDE
+    assert 'only when the user explicitly asks' in PARARAM_FORMATTING_GUIDE
+    assert 'ask the user for explicit confirmation' in PARARAM_FORMATTING_GUIDE
+    assert '[ ](task text)' in PARARAM_FORMATTING_REFERENCE