diff --git a/docs/migrate_from_openai_apps.md b/docs/migrate_from_openai_apps.md
index 01008cb4..3092f516 100644
--- a/docs/migrate_from_openai_apps.md
+++ b/docs/migrate_from_openai_apps.md
@@ -4,10 +4,17 @@ title: Migrate OpenAI App
 
 # Migrating from OpenAI Apps SDK to MCP Apps SDK
 
-This guide helps you migrate from the OpenAI Apps SDK to the MCP Apps SDK (`@modelcontextprotocol/ext-apps`).
+This reference maps OpenAI Apps SDK concepts to their MCP Apps SDK (`@modelcontextprotocol/ext-apps`) equivalents. Use the tables below for quick lookup during migration, and refer to the code examples for complete before/after comparisons.
+
+This guide covers server-side changes first (metadata, tools, resources), then client-side changes (setup, context, events).
+
+> [!NOTE]
+> Some OpenAI Apps SDK features don't have MCP equivalents yet. These are marked "Not yet implemented" in the tables below.
 
 ## Server-Side
 
+The server-side changes involve updating metadata structure and using helper functions.
+
 ### Quick Start Comparison
 
 | OpenAI Apps SDK                                            | MCP Apps SDK                                                   |
@@ -190,6 +197,8 @@ function createServer() {
 
 ## Client-Side
 
+Client-side migration involves replacing the implicit `window.openai` global with an explicit `App` instance.
+
 ### Quick Start Comparison
 
 | OpenAI Apps SDK                   | MCP Apps SDK                       |