From 06c0e08a1741e6aead754922e58b94aed69eaee7 Mon Sep 17 00:00:00 2001
From: martinalong <martina@anthropic.com>
Date: Wed, 17 Dec 2025 21:36:35 -0800
Subject: [PATCH] Clarify documentation

---
 specification/draft/apps.mdx | 10 ++++-----
 src/generated/schema.json    | 42 ++++++++++++++++++------------------
 src/generated/schema.ts      | 30 ++++++++++++++++----------
 src/spec.types.ts            | 10 ++++-----
 4 files changed, 50 insertions(+), 42 deletions(-)

diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx
index c7d9838..facb348 100644
--- a/specification/draft/apps.mdx
+++ b/specification/draft/apps.mdx
@@ -463,14 +463,14 @@ interface HostContext {
   availableDisplayModes?: string[];
   /** Current and maximum dimensions available to the UI. */
   viewport?: {
-    /** Current viewport width in pixels. */
+    /** Viewport width (if fixed). Only pass width or maxWidth, not both. */
     width?: number;
-    /** Current viewport height in pixels. */
+    /** Viewport height (if fixed). Only pass height or maxHeight, not both. */
     height?: number;
-    /** Maximum available height in pixels (if constrained). */
-    maxHeight?: number;
-    /** Maximum available width in pixels (if constrained). */
+    /** Maximum available viewport width in pixels (if constrained). */
     maxWidth?: number;
+    /** Maximum available viewport height in pixels (if constrained). */
+    maxHeight?: number;
   };
   /** User's language/region preference (BCP 47, e.g., "en-US") */
   locale?: string;
diff --git a/src/generated/schema.json b/src/generated/schema.json
index 839e174..6895edc 100644
--- a/src/generated/schema.json
+++ b/src/generated/schema.json
@@ -633,19 +633,19 @@
               "type": "object",
               "properties": {
                 "width": {
-                  "description": "Current viewport width in pixels.",
+                  "description": "Viewport width in pixels (if fixed). Only pass width or maxWidth, not both.",
                   "type": "number"
                 },
                 "height": {
-                  "description": "Current viewport height in pixels.",
-                  "type": "number"
-                },
-                "maxHeight": {
-                  "description": "Maximum available height in pixels (if constrained).",
+                  "description": "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
                   "type": "number"
                 },
                 "maxWidth": {
-                  "description": "Maximum available width in pixels (if constrained).",
+                  "description": "Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.",
+                  "type": "number"
+                },
+                "maxHeight": {
+                  "description": "Maximum available viewport height in pixels (if constrained). Only pass height or maxHeight, not both.",
                   "type": "number"
                 }
               },
@@ -1258,19 +1258,19 @@
           "type": "object",
           "properties": {
             "width": {
-              "description": "Current viewport width in pixels.",
+              "description": "Viewport width in pixels (if fixed). Only pass width or maxWidth, not both.",
               "type": "number"
             },
             "height": {
-              "description": "Current viewport height in pixels.",
-              "type": "number"
-            },
-            "maxHeight": {
-              "description": "Maximum available height in pixels (if constrained).",
+              "description": "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
               "type": "number"
             },
             "maxWidth": {
-              "description": "Maximum available width in pixels (if constrained).",
+              "description": "Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.",
+              "type": "number"
+            },
+            "maxHeight": {
+              "description": "Maximum available viewport height in pixels (if constrained). Only pass height or maxHeight, not both.",
               "type": "number"
             }
           },
@@ -2416,19 +2416,19 @@
               "type": "object",
               "properties": {
                 "width": {
-                  "description": "Current viewport width in pixels.",
+                  "description": "Viewport width in pixels (if fixed). Only pass width or maxWidth, not both.",
                   "type": "number"
                 },
                 "height": {
-                  "description": "Current viewport height in pixels.",
-                  "type": "number"
-                },
-                "maxHeight": {
-                  "description": "Maximum available height in pixels (if constrained).",
+                  "description": "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
                   "type": "number"
                 },
                 "maxWidth": {
-                  "description": "Maximum available width in pixels (if constrained).",
+                  "description": "Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.",
+                  "type": "number"
+                },
+                "maxHeight": {
+                  "description": "Maximum available viewport height in pixels (if constrained). Only pass height or maxHeight, not both.",
                   "type": "number"
                 }
               },
diff --git a/src/generated/schema.ts b/src/generated/schema.ts
index f6deae5..2c73ad6 100644
--- a/src/generated/schema.ts
+++ b/src/generated/schema.ts
@@ -565,26 +565,34 @@ export const McpUiHostContextSchema = z.looseObject({
   /** @description Current and maximum dimensions available to the UI. */
   viewport: z
     .object({
-      /** @description Current viewport width in pixels. */
+      /** @description Viewport width in pixels (if fixed). Only pass width or maxWidth, not both. */
       width: z
         .number()
         .optional()
-        .describe("Current viewport width in pixels."),
-      /** @description Current viewport height in pixels. */
+        .describe(
+          "Viewport width in pixels (if fixed). Only pass width or maxWidth, not both.",
+        ),
+      /** @description Viewport height in pixels (if fixed). Only pass height or maxHeight, not both. */
       height: z
         .number()
         .optional()
-        .describe("Current viewport height in pixels."),
-      /** @description Maximum available height in pixels (if constrained). */
-      maxHeight: z
-        .number()
-        .optional()
-        .describe("Maximum available height in pixels (if constrained)."),
-      /** @description Maximum available width in pixels (if constrained). */
+        .describe(
+          "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
+        ),
+      /** @description Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.*/
       maxWidth: z
         .number()
         .optional()
-        .describe("Maximum available width in pixels (if constrained)."),
+        .describe(
+          "Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.",
+        ),
+      /** @description Maximum available viewport height in pixels (if constrained). Only pass height or maxHeight, not both. */
+      maxHeight: z
+        .number()
+        .optional()
+        .describe(
+          "Maximum available viewport height in pixels (if constrained). Only pass height or maxHeight, not both.",
+        ),
     })
     .optional()
     .describe("Current and maximum dimensions available to the UI."),
diff --git a/src/spec.types.ts b/src/spec.types.ts
index 13ee625..8f04e7e 100644
--- a/src/spec.types.ts
+++ b/src/spec.types.ts
@@ -326,14 +326,14 @@ export interface McpUiHostContext {
   availableDisplayModes?: string[];
   /** @description Current and maximum dimensions available to the UI. */
   viewport?: {
-    /** @description Current viewport width in pixels. */
+    /** @description Viewport width in pixels (if fixed). Only pass width or maxWidth, not both. */
     width?: number;
-    /** @description Current viewport height in pixels. */
+    /** @description Viewport height in pixels (if fixed). Only pass height or maxHeight, not both. */
     height?: number;
-    /** @description Maximum available height in pixels (if constrained). */
-    maxHeight?: number;
-    /** @description Maximum available width in pixels (if constrained). */
+    /** @description Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.*/
     maxWidth?: number;
+    /** @description Maximum available viewport height in pixels (if constrained). Only pass height or maxHeight, not both. */
+    maxHeight?: number;
   };
   /** @description User's language and region preference in BCP 47 format. */
   locale?: string;