diff --git a/oas_docs/bundle.json b/oas_docs/bundle.json
index 0fde92c1fa3f..a4c1e30c8cf0 100644
--- a/oas_docs/bundle.json
+++ b/oas_docs/bundle.json
@@ -1304,14 +1304,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -2083,14 +2086,17 @@
                   },
                   "flapping": {
                     "additionalProperties": false,
+                    "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                     "nullable": true,
                     "properties": {
                       "look_back_window": {
+                        "description": "The minimum number of runs in which the threshold must be met.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
                       },
                       "status_change_threshold": {
+                        "description": "The minimum number of times an alert must switch states in the look back window.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
@@ -2484,14 +2490,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -3253,14 +3262,17 @@
                   },
                   "flapping": {
                     "additionalProperties": false,
+                    "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                     "nullable": true,
                     "properties": {
                       "look_back_window": {
+                        "description": "The minimum number of runs in which the threshold must be met.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
                       },
                       "status_change_threshold": {
+                        "description": "The minimum number of times an alert must switch states in the look back window.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
@@ -3647,14 +3659,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -5094,14 +5109,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
diff --git a/oas_docs/bundle.serverless.json b/oas_docs/bundle.serverless.json
index 229bda84b862..a0bd0c4cc434 100644
--- a/oas_docs/bundle.serverless.json
+++ b/oas_docs/bundle.serverless.json
@@ -1304,14 +1304,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -2083,14 +2086,17 @@
                   },
                   "flapping": {
                     "additionalProperties": false,
+                    "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                     "nullable": true,
                     "properties": {
                       "look_back_window": {
+                        "description": "The minimum number of runs in which the threshold must be met.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
                       },
                       "status_change_threshold": {
+                        "description": "The minimum number of times an alert must switch states in the look back window.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
@@ -2484,14 +2490,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -3253,14 +3262,17 @@
                   },
                   "flapping": {
                     "additionalProperties": false,
+                    "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                     "nullable": true,
                     "properties": {
                       "look_back_window": {
+                        "description": "The minimum number of runs in which the threshold must be met.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
                       },
                       "status_change_threshold": {
+                        "description": "The minimum number of times an alert must switch states in the look back window.",
                         "maximum": 20,
                         "minimum": 2,
                         "type": "number"
@@ -3647,14 +3659,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
@@ -5094,14 +5109,17 @@
                     },
                     "flapping": {
                       "additionalProperties": false,
+                      "description": "When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.",
                       "nullable": true,
                       "properties": {
                         "look_back_window": {
+                          "description": "The minimum number of runs in which the threshold must be met.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
                         },
                         "status_change_threshold": {
+                          "description": "The minimum number of times an alert must switch states in the look back window.",
                           "maximum": 20,
                           "minimum": 2,
                           "type": "number"
diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml
index 9f0c38baded7..117e52586c5a 100644
--- a/oas_docs/output/kibana.serverless.yaml
+++ b/oas_docs/output/kibana.serverless.yaml
@@ -1018,14 +1018,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -1600,14 +1610,24 @@ paths:
                   type: boolean
                 flapping:
                   additionalProperties: false
+                  description: >-
+                    When flapping detection is turned on, alerts that switch
+                    quickly between active and recovered states are identified
+                    as “flapping” and notifications are reduced.
                   nullable: true
                   type: object
                   properties:
                     look_back_window:
+                      description: >-
+                        The minimum number of runs in which the threshold must
+                        be met.
                       maximum: 20
                       minimum: 2
                       type: number
                     status_change_threshold:
+                      description: >-
+                        The minimum number of times an alert must switch states
+                        in the look back window.
                       maximum: 20
                       minimum: 2
                       type: number
@@ -1925,14 +1945,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -2510,14 +2540,24 @@ paths:
                     - active
                 flapping:
                   additionalProperties: false
+                  description: >-
+                    When flapping detection is turned on, alerts that switch
+                    quickly between active and recovered states are identified
+                    as “flapping” and notifications are reduced.
                   nullable: true
                   type: object
                   properties:
                     look_back_window:
+                      description: >-
+                        The minimum number of runs in which the threshold must
+                        be met.
                       maximum: 20
                       minimum: 2
                       type: number
                     status_change_threshold:
+                      description: >-
+                        The minimum number of times an alert must switch states
+                        in the look back window.
                       maximum: 20
                       minimum: 2
                       type: number
@@ -2807,14 +2847,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -3852,14 +3902,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
index 50fd92fdc8a9..82acbdb311f2 100644
--- a/oas_docs/output/kibana.yaml
+++ b/oas_docs/output/kibana.yaml
@@ -1367,14 +1367,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -1948,14 +1958,24 @@ paths:
                   type: boolean
                 flapping:
                   additionalProperties: false
+                  description: >-
+                    When flapping detection is turned on, alerts that switch
+                    quickly between active and recovered states are identified
+                    as “flapping” and notifications are reduced.
                   nullable: true
                   type: object
                   properties:
                     look_back_window:
+                      description: >-
+                        The minimum number of runs in which the threshold must
+                        be met.
                       maximum: 20
                       minimum: 2
                       type: number
                     status_change_threshold:
+                      description: >-
+                        The minimum number of times an alert must switch states
+                        in the look back window.
                       maximum: 20
                       minimum: 2
                       type: number
@@ -2273,14 +2293,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -2857,14 +2887,24 @@ paths:
                     - active
                 flapping:
                   additionalProperties: false
+                  description: >-
+                    When flapping detection is turned on, alerts that switch
+                    quickly between active and recovered states are identified
+                    as “flapping” and notifications are reduced.
                   nullable: true
                   type: object
                   properties:
                     look_back_window:
+                      description: >-
+                        The minimum number of runs in which the threshold must
+                        be met.
                       maximum: 20
                       minimum: 2
                       type: number
                     status_change_threshold:
+                      description: >-
+                        The minimum number of times an alert must switch states
+                        in the look back window.
                       maximum: 20
                       minimum: 2
                       type: number
@@ -3154,14 +3194,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
@@ -4191,14 +4241,24 @@ paths:
                       - last_execution_date
                   flapping:
                     additionalProperties: false
+                    description: >-
+                      When flapping detection is turned on, alerts that switch
+                      quickly between active and recovered states are identified
+                      as “flapping” and notifications are reduced.
                     nullable: true
                     type: object
                     properties:
                       look_back_window:
+                        description: >-
+                          The minimum number of runs in which the threshold must
+                          be met.
                         maximum: 20
                         minimum: 2
                         type: number
                       status_change_threshold:
+                        description: >-
+                          The minimum number of times an alert must switch
+                          states in the look back window.
                         maximum: 20
                         minimum: 2
                         type: number
diff --git a/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts b/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts
index 4844a9e808ef..acdd35854df3 100644
--- a/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts
+++ b/x-pack/plugins/alerting/common/routes/rule/common/flapping/schemas/v1.ts
@@ -17,13 +17,24 @@ import { validateFlapping as validateFlappingV1 } from '../../../validation/vali
 export const flappingSchema = schema.object(
   {
     look_back_window: schema.number({
+      meta: { description: 'The minimum number of runs in which the threshold must be met.' },
       min: MIN_LOOK_BACK_WINDOW_V1,
       max: MAX_LOOK_BACK_WINDOW_V1,
     }),
     status_change_threshold: schema.number({
+      meta: {
+        description:
+          'The minimum number of times an alert must switch states in the look back window.',
+      },
       min: MIN_STATUS_CHANGE_THRESHOLD_V1,
       max: MAX_STATUS_CHANGE_THRESHOLD_V1,
     }),
   },
-  { validate: validateFlappingV1 }
+  {
+    validate: validateFlappingV1,
+    meta: {
+      description:
+        'When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.',
+    },
+  }
 );