diff --git a/docs/subsystems/user-questions.md b/docs/subsystems/user-questions.md
index 7ff030b698..2a2463b475 100644
--- a/docs/subsystems/user-questions.md
+++ b/docs/subsystems/user-questions.md
@@ -52,9 +52,9 @@ type AskUserQuestionIntent = {
   reject: string
   /** Optional persistent grant offered only when the caller supports it. */
   always?: string
-  /** Metadata for human recognition, independent of the caller's authorization identity. */
+  /** Metadata for human recognition; the caller admits icon sources, which the UI may load as URLs. Never an authorization identity. */
   subject?: { name: string; icon?: string }
-  /** Localized presentation; option labels remain the wire answer values. */
+  /** Localized question and limited-grant label; fixed cards own reject/always wording. Option labels remain answer values. */
   display?: {
     question: { en: string; [locale: string]: string }
     detail?: { en: string; [locale: string]: string }
diff --git a/docs/subsystems/user-questions.zh.md b/docs/subsystems/user-questions.zh.md
index 176db66aec..f433339045 100644
--- a/docs/subsystems/user-questions.zh.md
+++ b/docs/subsystems/user-questions.zh.md
@@ -52,9 +52,9 @@ type AskUserQuestionIntent = {
   reject: string
   /** Optional persistent grant offered only when the caller supports it. */
   always?: string
-  /** Metadata for human recognition, independent of the caller's authorization identity. */
+  /** Metadata for human recognition; the caller admits icon sources, which the UI may load as URLs. Never an authorization identity. */
   subject?: { name: string; icon?: string }
-  /** Localized presentation; option labels remain the wire answer values. */
+  /** Localized question and limited-grant label; fixed cards own reject/always wording. Option labels remain answer values. */
   display?: {
     question: { en: string; [locale: string]: string }
     detail?: { en: string; [locale: string]: string }
diff --git a/packages/client/ui-approval/src/client/contract/slots.ts b/packages/client/ui-approval/src/client/contract/slots.ts
index e2b88d474b..2df54a54c4 100644
--- a/packages/client/ui-approval/src/client/contract/slots.ts
+++ b/packages/client/ui-approval/src/client/contract/slots.ts
@@ -211,7 +211,7 @@ export interface ApprovalCardInput {
   title: string
   /** Localized scope or consequence of the decision. */
   description?: string
-  /** Subject metadata for human recognition; never an authorization identity. */
+  /** Subject metadata for human recognition; the caller admits icon URLs. Never an authorization identity. */
   subject?: { name: string; icon?: string }
   /** Optional tool-owned detail rendered through the existing child slot. */
   callId?: ToolCallId
diff --git a/packages/interaction/user-questions/src/types.ts b/packages/interaction/user-questions/src/types.ts
index b90dc8d70a..25340a3009 100644
--- a/packages/interaction/user-questions/src/types.ts
+++ b/packages/interaction/user-questions/src/types.ts
@@ -41,9 +41,9 @@ export type AskUserQuestionIntent = {
   reject: string
   /** Optional persistent grant offered only when the caller supports it. */
   always?: string
-  /** Metadata for human recognition, independent of the caller's authorization identity. */
+  /** Metadata for human recognition; the caller admits icon sources, which the UI may load as URLs. Never an authorization identity. */
   subject?: { name: string; icon?: string }
-  /** Localized presentation; option labels remain the wire answer values. */
+  /** Localized question and limited-grant label; fixed cards own reject/always wording. Option labels remain answer values. */
   display?: {
     question: { en: string; [locale: string]: string }
     detail?: { en: string; [locale: string]: string }