===================================================================
--- a/actions/view-screen.ts
+++ b/actions/view-screen.ts
@@ -1,11 +1,20 @@
+/**
+ * See what the user is currently looking at on screen.
+ *
+ * Reads and returns the current navigation state from application state.
+ *
+ * Usage:
+ *   pnpm action view-screen
+ */
+
 import { defineAction } from "@agent-native/core/action";
 import { readAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 
 export default defineAction({
   description:
-    "Read the Chat app's current navigation state. Basic navigation is already included in <current-screen>; use this action only when you need a fresh read.",
+    "See what the user is currently looking at on screen. Returns the current navigation state for the app canvas plus agent rail. Always call this first before taking any action.",
   schema: z.object({}),
   http: false,
   readOnly: true,
   run: async () => {