Clarify documentation

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). */
+    /** Maximum available viewport width in pixels (if constrained). */
-    maxHeight?: number;
-    /** Maximum available 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;

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.",
+                  "description": "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
-                  "type": "number"
-                },
-                "maxHeight": {
-                  "description": "Maximum available height in pixels (if constrained).",
                   "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.",
+              "description": "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
-              "type": "number"
-            },
-            "maxHeight": {
-              "description": "Maximum available height in pixels (if constrained).",
               "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.",
+                  "description": "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
-                  "type": "number"
-                },
-                "maxHeight": {
-                  "description": "Maximum available height in pixels (if constrained).",
                   "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"
                 }
               },

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."),
+        .describe(
-      /** @description Current viewport height in pixels. */
+          "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."),
+        .describe(
-      /** @description Maximum available height in pixels (if constrained). */
+          "Viewport height in pixels (if fixed). Only pass height or maxHeight, not both.",
-      maxHeight: z
+        ),
-        .number()
+      /** @description Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.*/
-        .optional()
-        .describe("Maximum available height in pixels (if constrained)."),
-      /** @description Maximum available width in pixels (if constrained). */
       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."),

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). */
+    /** @description Maximum available viewport width in pixels (if constrained). Only pass width or maxWidth, not both.*/
-    maxHeight?: number;
-    /** @description Maximum available width in pixels (if constrained). */
     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;