diff --git a/oas_docs/bundle.json b/oas_docs/bundle.json
index a0469257cacd2..256c2f000554c 100644
--- a/oas_docs/bundle.json
+++ b/oas_docs/bundle.json
@@ -1853,14 +1853,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"
@@ -2690,14 +2693,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"
@@ -3091,14 +3097,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"
@@ -3918,14 +3927,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"
@@ -4312,14 +4324,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"
@@ -5817,14 +5832,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.yaml b/oas_docs/output/kibana.yaml
index be8a00b795e33..6cffba350bcf4 100644
--- a/oas_docs/output/kibana.yaml
+++ b/oas_docs/output/kibana.yaml
@@ -1652,14 +1652,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
@@ -2425,14 +2435,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
@@ -2825,14 +2845,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
@@ -3577,14 +3607,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
@@ -3969,14 +4009,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
@@ -5205,14 +5255,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 4844a9e808ef5..acdd35854df3f 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.',
+    },
+  }
 );