docs(skill): add UI support check and data handling gotchas

Author: antonpk1

plugins/mcp-apps/skills/create-mcp-app/SKILL.md

@@ -41,6 +41,34 @@ Host calls tool → Server returns result → Host renders resource UI → UI re
 - Register tools and resources
 - Configure build system with `vite-plugin-singlefile`
 
+### Checking Host UI Support
+
+Not all hosts support MCP Apps. Use `hasUiSupport()` to conditionally register UI-enabled tools:
+
+```typescript
+import { hasUiSupport, registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+
+server.oninitialized = ({ clientCapabilities }) => {
+  if (hasUiSupport(clientCapabilities)) {
+    // Register tool with UI
+    registerAppTool(server, "weather", {
+      description: "Get weather with interactive dashboard",
+      _meta: { ui: { resourceUri: "ui://weather/dashboard" } },
+    }, weatherHandler);
+  } else {
+    // Register text-only fallback for hosts without UI support
+    server.registerTool("weather", {
+      description: "Get weather as text",
+    }, textWeatherHandler);
+  }
+};
+```
+
+**Key points:**
+- Check `clientCapabilities` in `oninitialized` callback
+- `hasUiSupport()` checks both `experimental` and `extensions` fields
+- Provide text-only fallback for non-UI hosts
+
 ## Getting Reference Code
 
 Clone the SDK repository for working examples and API documentation:
@@ -312,6 +340,30 @@ See `examples/shadertoy-server/` for complete implementation.
 6. **No text fallback** - Always provide `content` array for non-UI hosts
 7. **Hardcoded styles** - Use host CSS variables for theme integration
 8. **No streaming for large inputs** - Use `ontoolinputpartial` to show progress during generation
+9. **Non-visual binary data in `content` or `structuredContent`** - Use `_meta` instead
+
+## Data Handling: content vs structuredContent vs _meta
+
+| Field | Goes to model? | Use for |
+|-------|---------------|---------|
+| `content` | ✅ YES | Text + images (model sees with vision) |
+| `structuredContent` | ✅ YES (as text) | Structured JSON for model + UI |
+| `_meta` | ❌ NO | PDFs, audio, large blobs - UI only |
+
+**Critical**: Non-visual binary data (PDFs, audio, etc.) in `content` or `structuredContent` wastes tokens as nonsense base64. Use `_meta`.
+
+```typescript
+// ❌ WRONG - model sees meaningless base64 string
+return {
+  structuredContent: { pdfData: base64Pdf }
+};
+
+// ✅ CORRECT - model gets summary, UI gets PDF from _meta
+return {
+  content: [{ type: "text", text: "Generated invoice #1234" }],
+  _meta: { pdfData: base64Pdf, mimeType: "application/pdf" }
+};
+```
 
 ## Testing