Suggestions for new message format guidance article

msteams-platform/TOC.yml

@@ -264,7 +264,7 @@
         - name: Bots with tabs
           href: resources/bot-v3/bots-with-tabs.md
         - name: Format bot messages
-          href: resources/bot-v3/bots-text-formats.md  
+          href: resources/bot-v3/bots-text-formats.md
         - name: Test a bot
           href: resources/bot-v3/bots-test.md
       - name: Message extensions SDK (v3)
@@ -565,6 +565,9 @@
       - name: Format the bot messages
         href: bots/how-to/format-your-bot-messages.md
         displayName: cross-platform support
+      - name: Format the bot messages
+        href: agents-in-teams/agent-message-format-guidance.md
+        displayName: markdown, text, widget, mcp-ui, adaptive, card, choose, best practice
       - name: Send and receive files
         href: bots/how-to/bots-filesv4.md  
         displayName: receive files using bot

msteams-platform/agents-in-teams/agent-message-format-guidance.md

@@ -1,6 +1,17 @@
-# Teams Agent Message Format Design Guidance
+---
+title: Message format design guidance for Teams agents
+description: Message format design for Teams agents shows you when to use plain text, Markdown, Adaptive Cards, or widgets. Learn to match each format to your users need.
+#customer intent: As a Teams agent developer, I want to understand the four available types of message content so that I can choose the right one for my agent's responses.
+author: luywang
+ms.author: luywang
+ms.reviewer: nickwalk
+ms.date: 07/10/2026
+ms.topic: best-practice
+---
 
-Teams agents can respond using four message formats. Choosing the right format optimizes user experience by preventing cognitive overload, missed actions, or broken experiences. This guide helps you pick the right format based on what you're communicating and what the user needs to do.
+# Message format design guidance for agents
+
+Chat messages sent by Teams agents can contain four different kinds of content. Choosing the right format optimizes user experience by preventing cognitive overload, missed actions, and broken experiences. This guide helps you pick the right format based on what you're communicating and what the user needs to do.
 
 | Format | Best For | Complexity of Implementation |
 |---|---|---|
@@ -9,17 +20,13 @@ Teams agents can respond using four message formats. Choosing the right format o
 | Adaptive Card | Actionable content, approvals, forms, structured data | Medium – High |
 | Widget / MCP-UI | Rich, live, stateful experiences with custom UI | High |
 
-
-
 ## Key Principles
 
 1. **Default to the simplest format that meets the need.** Plain Text → Markdown → Adaptive Card → Widget. Don't over-engineer.
 2. **Cards are for action, not decoration.** If there's no button, a card is probably overkill.
-3. **Widgets are an escalation path, not a default.** Validate on Adaptive Cards first; escalate only when cards hit a hard UI ceiling.
+3. **Prefer Adaptive Cards to Widgets when possible.** Use a widget only after confirming that the desired experience isn't possible with an Adaptive Cards.
 4. **Match the surface.** Mobile Teams has limited widget support. Adaptive Cards are the safest cross-surface choice for interactive content.
-5. **Avoid format mixing in a single turn.** A markdown block followed by a card in the same message creates visual noise. Pick one.
-
-
+5. **Use a single content type per message.** A markdown block followed by a card in the same message creates visual noise. Pick one.
 
 ## Format Profiles
 
@@ -28,20 +35,21 @@ Teams agents can respond using four message formats. Choosing the right format o
 Use when the response is conversational, brief, or a single-sentence fact. Plain text feels like chatting, loads instantly, and requires zero rendering overhead.
 
 **Use for:**
-- "What time is the team sync?" → "Your team sync is at 2 PM Pacific today."
+
+- Simple answers to questions: "Your team sync is at 2 PM Pacific today."
 - Confirming an action: "Done — I've sent the invite to Alex."
 - Error nudges: "I couldn't find that file. Can you share the link?"
 - Status pings: "The deployment finished 3 minutes ago."
-- Quick clarifications in a back-and-forth dialog
+- Quick clarifications in a back-and-forth dialog: "Do you want to send the invitation now?"
 
 **Avoid when:** Content has lists, tables, code, or anything the user needs to scan rather than read linearly.
 
-
 ### Markdown
 
 Use when you need lightweight structure — headers, bullets, bold, inline code — but no interactivity. Markdown renders natively in Teams chat and channel posts.
 
 **Use for:**
+
 - Meeting recap with bullet-point action items
 - Code snippet with syntax highlighting (inline code or fenced blocks)
 - Numbered troubleshooting steps or release notes
@@ -50,12 +58,12 @@ Use when you need lightweight structure — headers, bullets, bold, inline code
 
 **Avoid when:** Content has more than ~3 data columns, or when the user must take an action (click, approve, fill a field).
 
-
 ### Adaptive Card
 
 Use when structure meets interaction — approvals, form inputs, rich data tables, status dashboards, or any scenario where the user must act on the content.
 
 **Use for:**
+
 - Approval workflow: "Please approve this PR" with [Approve] / [Reject] buttons
 - Incident alert with severity badge, owner field, and [Acknowledge] CTA
 - Expense report form with dropdowns and text fields
@@ -64,12 +72,12 @@ Use when structure meets interaction — approvals, form inputs, rich data table
 
 **Avoid when:** Content is purely informational (use Markdown); or data is live and needs real-time refresh (use Widget).
 
-
 ### Widget / MCP-UI
 
 Use for rich, stateful, interactive experiences beyond what a card can offer — embedded charts, live data, multi-step flows, or custom UI. Widgets render as a pane, not inline in chat.
 
 **Use for:**
+
 - Interactive data explorer: filter a table, drill into a row, export CSV
 - Multi-step onboarding wizard collecting info across 4–5 screens
 - Canvas-style Kanban board with drag-and-drop
@@ -78,10 +86,7 @@ Use for rich, stateful, interactive experiences beyond what a card can offer —
 
 **Avoid when:** The experience fits in a card (use Adaptive Cards instead), or the UI is too rich to belong in a Teams message at all — a full analytics suite, an interactive CAD viewer, or any app-scale UI should live on the web and be linked to, not embedded. Widgets occupy the middle ground: richer than a card, scoped enough to feel native, but they do not replace the rich experience of a full app. Widgets have higher latency, require extra infrastructure, and have limited support on mobile / classic Teams. Default to Adaptive Cards; escalate to Widget only when cards hit a hard ceiling.
 
-
-:::image type="content" source="../assets/images/agents-in-teams/teams-message-format-decision-tree-wide-v2.png" alt-text="Image shows a decision tree for agent to choose the right message format." border="false":::
-
-
+:::image type="content" source="../assets/images/agents-in-teams/teams-message-format-decision-tree-wide.png" alt-text="Image shows a decision tree for agent to choose the right message format." lightbox="../assets/images/agents-in-teams/teams-message-format-decision-tree-wide.png" border="false":::
 
 ## Quick-Reference Cheat Sheet