diff --git a/packages/twenty-docs/developers/extend/apps/layout/command-menu-items.mdx b/packages/twenty-docs/developers/extend/apps/layout/command-menu-items.mdx
index 91f258cb2f9..35078122d67 100644
--- a/packages/twenty-docs/developers/extend/apps/layout/command-menu-items.mdx
+++ b/packages/twenty-docs/developers/extend/apps/layout/command-menu-items.mdx
@@ -103,6 +103,10 @@ export default defineCommandMenuItem({
 });
 ```
 
+<Note>
+  `RECORD_SELECTION` already implies a non-empty selection — use `numberOfSelectedRecords` only for specific counts (e.g. `>= 2`).
+</Note>
+
 ### Context variables
 
 These represent the current state of the page: