Appendix C: Gotchas Compendium
Every Platform Gotcha from every Gem, consolidated and cross-referenced. Check here before deploying.
Channel Limitations
| Gotcha |
Severity |
Source Gem |
| ConversationStart topic does NOT fire in M365 Copilot. Use agent instructions instead. |
🔴 Critical |
GEM-001, 004, 005, 007, 014, 017 |
| M365 Copilot does NOT support proactive messaging. Plan around Teams. |
🔴 Critical |
GEM-014 |
| M365 Copilot does NOT support Fabric Data Agent connections. |
🟡 Medium |
GEM-028 |
| M365 Copilot does NOT support Omnichannel handoff. |
🟡 Medium |
GEM-010 |
System.Conversation.InTestMode is always false outside Test Canvas. |
🟡 Medium |
GEM-004 |
Adaptive Card Action.ShowCard rendering varies by channel. Test in target channel. |
🟡 Medium |
GEM-003, 004, 006 |
| M365 Copilot may batch rapidly-sent sequential messages. |
🟡 Low |
GEM-003 |
Knowledge & Search
| Gotcha |
Severity |
Source Gem |
| PDF tables break SharePoint knowledge retrieval. Use Word (.docx). |
🔴 Critical |
GEM-008 |
SearchAndSummarizeContent does NOT return document URLs. |
🟡 Medium |
GEM-018 |
| SharePoint indexing has a delay (5-30 min) after upload. |
🟡 Medium |
GEM-008 |
| SharePoint file limit: 7 MB without M365 Copilot license. |
🟡 Medium |
GEM-008 |
| Max 500 knowledge objects per agent. |
🟡 Medium |
GEM-026 |
| Azure AI Search VNet indexes not supported by Copilot Studio. |
🟡 Medium |
GEM-026 |
| Only ONE vector index per Azure AI Search connection. |
🟡 Medium |
GEM-026 |
Security & Data
| Gotcha |
Severity |
Source Gem |
LLM instruction-based gating is NOT a security boundary. Add hard ConditionGroup checks. |
🔴 Critical |
GEM-007, 015, 022 |
| Platform logs capture raw user messages (including PII). |
🔴 Critical |
GEM-022 |
| Never expose Direct Line secrets in client-side code. |
🔴 Critical |
GEM-025 |
System.User.Id format varies by channel. Test in target channel. |
🟡 Medium |
GEM-001 |
Integration
| Gotcha |
Severity |
Source Gem |
| MCP requires Generative Orchestration. Manual topics can't call MCP tools. |
🟡 Medium |
GEM-023 |
| MCP SSE transport deprecated after August 2025. Use Streamable HTTP. |
🟡 Medium |
GEM-023 |
| Power Automate flow failures may not return to agent gracefully. Check for blank outputs. |
🟡 Medium |
GEM-009 |
| HttpRequest default timeout may be 30+ seconds. Set explicit timeouts (5-10s). |
🟡 Medium |
GEM-009 |
| Power Automate flow runs count against quota. Plan licensing. |
🟡 Medium |
GEM-001, 012, 015 |
Agent Instructions
| Gotcha |
Severity |
Source Gem |
| Instructions degrade past ~3,000-4,000 words. Modularize (GEM-020). |
🟡 Medium |
GEM-002, 020 |
| Generative orchestration routes by description, not rules. Write clear descriptions. |
🟡 Medium |
GEM-002, 021 |
alwaysPrompt: true required for mandatory questions in regulated flows. |
🟡 Medium |
GEM-027 |
startBehavior: CancelOtherTopics essential for regulated flows. |
🟡 Medium |
GEM-027 |
| Gotcha |
Severity |
Source Gem |
| Copilot Studio doesn't expose actual token counts. Estimation only. |
🟡 Medium |
GEM-012 |
| Application Insights has ~2-5 min ingestion delay. Not real-time. |
🟡 Low |
GEM-004, 016 |
| CSAT survey response rates drop after first week. Show selectively. |
🟡 Low |
GEM-016 |
| Global variables reset between conversations. That's why GEM-001 exists. |
🟡 Low |
GEM-001, 004 |