From 7c3d1e817f4e2242c2e36b074f1e9036c2961bef Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Mon, 19 Jan 2026 10:08:37 -0600
Subject: [PATCH] Complete "Tools that are private to Apps" pattern
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the `_meta.ui.visibility: ["app"]` feature in `docs/patterns.md`
by referencing the existing type-checked example from
`src/server/index.examples.ts#registerAppTool_toolVisibility`.

- Fix typo: `["apps"]` → `["app"]` (singular)
- Remove placeholder function from `docs/patterns.ts`
- Expand description to explain use cases

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/patterns.md             |  6 +++---
 docs/patterns.ts             | 12 ------------
 src/server/index.examples.ts | 19 ++++++++++++-------
 src/server/index.ts          |  7 +++++--
 4 files changed, 20 insertions(+), 24 deletions(-)

diff --git a/docs/patterns.md b/docs/patterns.md
index a3eeaf9..c109cfd 100644
--- a/docs/patterns.md
+++ b/docs/patterns.md
@@ -6,11 +6,11 @@ title: Patterns
 
 This document covers common patterns and recipes for building MCP Apps.
 
-## [TODO] Tools that are private to Apps
+## Tools that are private to Apps
 
-Use `Tool._meta.ui.visibility: ["apps"]` to make tools only visible to Apps.
+Set {@link types!McpUiToolMeta.visibility Tool.\_meta.ui.visibility} to `["app"]` to make tools only callable by Apps (hidden from the model). This is useful for UI-driven actions like updating quantities, toggling settings, or other interactions that shouldn't appear in the model's tool list.
 
-{@includeCode ./patterns.ts#privateTools}
+{@includeCode ../src/server/index.examples.ts#registerAppTool_appOnlyVisibility}
 
 ## [TODO] Authenticated calls from App
 
diff --git a/docs/patterns.ts b/docs/patterns.ts
index 1321123..5ac8b91 100644
--- a/docs/patterns.ts
+++ b/docs/patterns.ts
@@ -9,17 +9,6 @@
 
 import { App } from "../src/app.js";
 
-// TODO: Add imports as patterns are implemented
-
-/**
- * Example: Tools that are private to Apps
- */
-function privateTools() {
-  //#region privateTools
-  // TODO: Tool._meta.ui.visibility: ["apps"]
-  //#endregion privateTools
-}
-
 /**
  * Example: Authenticated calls from App
  */
@@ -121,7 +110,6 @@ function migrateFromOpenai() {
 }
 
 // Suppress unused variable warnings
-void privateTools;
 void authenticatedCalls;
 void errorsToModel;
 void hostStyling;
diff --git a/src/server/index.examples.ts b/src/server/index.examples.ts
index 9c5ae66..128279c 100644
--- a/src/server/index.examples.ts
+++ b/src/server/index.examples.ts
@@ -86,11 +86,10 @@ function registerAppTool_basicUsage(server: McpServer) {
 }
 
 /**
- * Example: Tool visibility - create app-only tools for UI actions.
+ * Example: Model-only visibility - tools visible to model but not callable by UI.
  */
-function registerAppTool_toolVisibility(server: McpServer) {
-  //#region registerAppTool_toolVisibility
-  // Main tool - visible to both model and app (default)
+function registerAppTool_modelOnlyVisibility(server: McpServer) {
+  //#region registerAppTool_modelOnlyVisibility
   registerAppTool(
     server,
     "show-cart",
@@ -99,7 +98,7 @@ function registerAppTool_toolVisibility(server: McpServer) {
       _meta: {
         ui: {
           resourceUri: "ui://shop/cart.html",
-          visibility: ["model", "app"],
+          visibility: ["model"],
         },
       },
     },
@@ -108,8 +107,14 @@ function registerAppTool_toolVisibility(server: McpServer) {
       return { content: [{ type: "text", text: JSON.stringify(cart) }] };
     },
   );
+  //#endregion registerAppTool_modelOnlyVisibility
+}
 
-  // App-only tool - hidden from the model, only callable by the UI
+/**
+ * Example: App-only visibility - tools hidden from model, only callable by UI.
+ */
+function registerAppTool_appOnlyVisibility(server: McpServer) {
+  //#region registerAppTool_appOnlyVisibility
   registerAppTool(
     server,
     "update-quantity",
@@ -128,7 +133,7 @@ function registerAppTool_toolVisibility(server: McpServer) {
       return { content: [{ type: "text", text: JSON.stringify(cart) }] };
     },
   );
-  //#endregion registerAppTool_toolVisibility
+  //#endregion registerAppTool_appOnlyVisibility
 }
 
 /**
diff --git a/src/server/index.ts b/src/server/index.ts
index cbd9f1f..826c8b3 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -117,8 +117,11 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
  * @example Basic usage
  * {@includeCode ./index.examples.ts#registerAppTool_basicUsage}
  *
- * @example Tool visibility - create app-only tools for UI actions
- * {@includeCode ./index.examples.ts#registerAppTool_toolVisibility}
+ * @example Tool visible to model but not callable by UI
+ * {@includeCode ./index.examples.ts#registerAppTool_modelOnlyVisibility}
+ *
+ * @example Tool hidden from model, only callable by UI
+ * {@includeCode ./index.examples.ts#registerAppTool_appOnlyVisibility}
  *
  * @see {@link registerAppResource} to register the HTML resource referenced by the tool
  */