diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py
index 25d900341f49..765743c60f4d 100644
--- a/agent/prompt_builder.py
+++ b/agent/prompt_builder.py
@@ -805,8 +805,26 @@ PLATFORM_HINTS = {
     ),
     "matrix": (
         "You are in a Matrix room communicating with your user. "
-        "Matrix renders Markdown — bold, italic, code blocks, and links work; "
-        "the adapter converts your Markdown to HTML for rich display. "
+        "The adapter converts your Markdown to HTML for rich display.\n\n"
+        "CRITICAL FORMATTING RULES (Matrix renders Markdown inconsistently):\n\n"
+        "Supported and safe: **bold**, *italic*, `inline code`, ``` code blocks, "
+        "- bullet lists, [links](url), > blockquote, labeled **Label:** value pairs, "
+        "and key: value pairs.\n\n"
+        "Do NOT use (they render incorrectly or not at all):\n"
+        "- Tables — become one continuous line; use labeled **Label:** value pairs\n"
+        "- Numbered lists — collapse to bullets; use - bullets\n"
+        "- Horizontal rules (---) — invisible\n"
+        "- ||spoiler|| tags — no visual effect\n"
+        "- ~strikethrough~ — no visual effect\n"
+        "- Headings (# ## ###) — no visual effect\n"
+        "- Checkboxes (- [ ] / - [x]) — render as plain ASCII\n\n"
+        "LINEBREAKS ARE CRITICAL: A single newline does NOT create a new line — "
+        "adjacent lines merge together. Use TWO trailing spaces at the end of a "
+        "line for a soft linebreak. Use a blank line between paragraphs. "
+        "Without two trailing spaces or a blank line, everything runs together.\n\n"
+        "LINKS: Always use [descriptive link text](url) — never show bare URLs. "
+        "When referencing something with an associated URL (event names, venues, "
+        "people, sources), make the name a clickable link.\n\n"
         "You can send media files natively: include MEDIA:/absolute/path/to/file "
         "in your response. Images (.jpg, .png, .webp) are sent as inline photos, "
         "audio (.ogg, .mp3) as voice/audio messages, video (.mp4) inline, "