diff --git a/docs/reference/esql/functions/description/categorize.asciidoc b/docs/reference/esql/functions/description/categorize.asciidoc
index a5e8e2d507574..32af0051e91c8 100644
--- a/docs/reference/esql/functions/description/categorize.asciidoc
+++ b/docs/reference/esql/functions/description/categorize.asciidoc
@@ -3,3 +3,9 @@
 *Description*
 
 Groups text messages into categories of similarly formatted text values.
+
+`CATEGORIZE` has the following limitations:
+
+* can't be used within other expressions
+* can't be used with multiple groupings
+* can't be used or referenced within aggregations
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java
index ca0447ce11ec4..e2c04ecb15b59 100644
--- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java
+++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/grouping/Categorize.java
@@ -48,6 +48,12 @@ public class Categorize extends GroupingFunction implements Validatable {
     @FunctionInfo(
         returnType = "keyword",
         description = "Groups text messages into categories of similarly formatted text values.",
+        detailedDescription = """
+            `CATEGORIZE` has the following limitations:
+
+            * can't be used within other expressions
+            * can't be used with multiple groupings
+            * can't be used or referenced within aggregate functions""",
         examples = {
             @Example(
                 file = "docs",