diff --git a/docs/overlays/elasticsearch-shared-overlays.yaml b/docs/overlays/elasticsearch-shared-overlays.yaml
index 199475bb5d..b992e056ca 100644
--- a/docs/overlays/elasticsearch-shared-overlays.yaml
+++ b/docs/overlays/elasticsearch-shared-overlays.yaml
@@ -43,19 +43,19 @@ actions:
             This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/es-connectors-tutorial-api.html
-            description: Connector API tutorial
+            description: Check out the connector API tutorial
         - name: ccr
           x-displayName: Cross-cluster replication
       # D
         - name: data stream
           x-displayName: Data stream
           externalDocs:
-            description: Data stream overview 
+            description: Learn more about data streams. 
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/data-streams.html
         - name: document
           x-displayName: Document
           externalDocs:
-            description: Reading and writing documents
+            description: Learn more about reading and writing documents.
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-replication.html
       # E  
         - name: enrich
@@ -66,14 +66,14 @@ actions:
             Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/eql.html
-            description: EQL search
+            description: Learn more about EQL search.
         - name: esql
           x-displayName: ES|QL
           description: >
             The Elasticsearch Query Language (ES|QL) provides a powerful way to filter, transform, and analyze data stored in Elasticsearch, and in the future in other runtimes.
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/esql.html
-            description: ES|QL overview and tutorials
+            description: Learn more about ES|QL.
       # F
         - name: features
           description: The feature APIs enable you to introspect and manage features provided by Elasticsearch and Elasticsearch plugins.
@@ -87,7 +87,7 @@ actions:
             The graph explore API enables you to extract and summarize information about the documents and terms in an Elasticsearch data stream or index.
           externalDocs:
             url: https://www.elastic.co/guide/en/kibana/master/xpack-graph.html
-            description: Getting started with Graph
+            description: Get started with Graph.
       # I
         - name: indices
           x-displayName: Index
@@ -97,7 +97,7 @@ actions:
           x-displayName: Index lifecycle management
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/index-lifecycle-management.html
-            description: Manage the index lifecycle
+            description: Learn more about managing the index lifecycle.
         - name: inference
           x-displayName: Inference
           description: >
@@ -115,14 +115,14 @@ actions:
           description: Licensing APIs enable you to manage your licenses.
           externalDocs:
             url: https://www.elastic.co/subscriptions
-            description: For more information about the different types of licenses, refer to Elastic subscriptions
+            description: For more information about the different types of licenses, refer to Elastic subscriptions.
         - name: logstash
           x-displayName: Logstash
           description: >
             Logstash APIs enable you to manage pipelines that are used by Logstash Central Management.
           externalDocs:
             url: https://www.elastic.co/guide/en/logstash/master/logstash-centralized-pipeline-management.html
-            description: Centralized pipeline management
+            description: Learn more about centralized pipeline management.
       # M
         - name: ml
           x-displayName: Machine learning
@@ -131,19 +131,19 @@ actions:
           # description:
           externalDocs:
             url: https://www.elastic.co/guide/en/machine-learning/master/ml-ad-finding-anomalies.html
-            description: Finding anomalies
+            description: Learn more about finding anomalies.
         - name: ml data frame
           x-displayName: Machine learning data frame analytics
           # description:
           externalDocs:
             url: https://www.elastic.co/guide/en/machine-learning/master/ml-dfa-overview.html
-            description: Data frame analytics overview
+            description: Learn more about data frame analytics.
         - name: ml trained model
           x-displayName: Machine learning trained model
           # description:
           externalDocs:
             url: https://www.elastic.co/guide/en/machine-learning/master/ml-nlp-overview.html
-            description: Natural language processing overview
+            description: Learn more about natural language processing.
         - name: migration
           x-displayName: Migration
         - name: monitoring
@@ -163,7 +163,7 @@ actions:
             This allows pinning documents for only queries that match a specific term.
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/query-dsl-rule-query.html
-            description: Rule query
+            description: Learn more about the rule query.
       # R
         - name: rollup
           x-displayName: Rollup
@@ -184,21 +184,21 @@ actions:
             Snapshot and restore APIs enable you to set up snapshot repositories, manage snapshot backups, and restore snapshots to a running cluster.
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/snapshot-restore.html
-            description: Snapshot and restore
+            description: Learn more about snapshot and restore operations.
         - name: slm
           x-displayName: Snapshot lifecycle management
           description: >
             Snapshot lifecycle management (SLM) APIs enable you to set up policies to automatically take snapshots and control how long they are retained.
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/snapshots-take-snapshot.html
-            description: Create a snapshot
+            description: Learn more about creating a snapshot.
         - name: sql
           x-displayName: SQL
           description: >
             Elasticsearch's SQL APIs enable you to run SQL queries on Elasticsearch indices and data streams.
           externalDocs:
             url: https://www.elastic.co/guide/en/elasticsearch/reference/master/xpack-sql.html
-            description: An overview and tutorials for the Elasticsearch SQL features
+            description: Check out the overview and tutorials for the Elasticsearch SQL features.
         - name: synonyms
           x-displayName: Synonyms
           description: >
@@ -218,6 +218,11 @@ actions:
       # W
         - name: watcher
           x-displayName: Watcher
+          description: >
+            You can use Watcher to watch for changes or anomalies in your data and perform the necessary actions in response.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/master/xpack-alerting.html
+            description: Learn more about Watcher.
 # Add x-model and/or abbreviate schemas that should point to other references
   - target: "$.components['schemas']['_types.query_dsl:QueryContainer']"
     description: Add x-model for the QueryContainer object
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index e5fbf27751..d885cc159a 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -35757,7 +35757,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Acknowledges a watch, manually throttling the execution of the watch's actions",
+        "summary": "Acknowledge a watch",
+        "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.",
         "operationId": "watcher-ack-watch",
         "parameters": [
           {
@@ -35774,7 +35775,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Acknowledges a watch, manually throttling the execution of the watch's actions",
+        "summary": "Acknowledge a watch",
+        "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.",
         "operationId": "watcher-ack-watch-1",
         "parameters": [
           {
@@ -35793,7 +35795,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Acknowledges a watch, manually throttling the execution of the watch's actions",
+        "summary": "Acknowledge a watch",
+        "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.",
         "operationId": "watcher-ack-watch-2",
         "parameters": [
           {
@@ -35813,7 +35816,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Acknowledges a watch, manually throttling the execution of the watch's actions",
+        "summary": "Acknowledge a watch",
+        "description": "Acknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.",
         "operationId": "watcher-ack-watch-3",
         "parameters": [
           {
@@ -35835,7 +35839,11 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Activates a currently inactive watch",
+        "summary": "Activate a watch",
+        "description": "A watch can be either active or inactive.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/how-watcher-works.html"
+        },
         "operationId": "watcher-activate-watch",
         "parameters": [
           {
@@ -35852,7 +35860,11 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Activates a currently inactive watch",
+        "summary": "Activate a watch",
+        "description": "A watch can be either active or inactive.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/how-watcher-works.html"
+        },
         "operationId": "watcher-activate-watch-1",
         "parameters": [
           {
@@ -35871,7 +35883,11 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Deactivates a currently active watch",
+        "summary": "Deactivate a watch",
+        "description": "A watch can be either active or inactive.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/how-watcher-works.html"
+        },
         "operationId": "watcher-deactivate-watch",
         "parameters": [
           {
@@ -35888,7 +35904,11 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Deactivates a currently active watch",
+        "summary": "Deactivate a watch",
+        "description": "A watch can be either active or inactive.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/how-watcher-works.html"
+        },
         "operationId": "watcher-deactivate-watch-1",
         "parameters": [
           {
@@ -35907,7 +35927,7 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Retrieves a watch by its ID",
+        "summary": "Get a watch",
         "operationId": "watcher-get-watch",
         "parameters": [
           {
@@ -35967,7 +35987,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Creates a new watch, or updates an existing one",
+        "summary": "Create or update a watch",
+        "description": "When a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine.\nTypically for the `schedule` trigger, the scheduler is the trigger engine.\n\nIMPORTANT: You must use Kibana or this API to create a watch.\nDo not add a watch directly to the `.watches` index by using the Elasticsearch index API.\nIf Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.\n\nWhen you add a watch you can also define its initial active state by setting the *active* parameter.\n\nWhen Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.\nIf the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.",
         "operationId": "watcher-put-watch",
         "parameters": [
           {
@@ -35999,7 +36020,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Creates a new watch, or updates an existing one",
+        "summary": "Create or update a watch",
+        "description": "When a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine.\nTypically for the `schedule` trigger, the scheduler is the trigger engine.\n\nIMPORTANT: You must use Kibana or this API to create a watch.\nDo not add a watch directly to the `.watches` index by using the Elasticsearch index API.\nIf Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.\n\nWhen you add a watch you can also define its initial active state by setting the *active* parameter.\n\nWhen Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.\nIf the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.",
         "operationId": "watcher-put-watch-1",
         "parameters": [
           {
@@ -36031,7 +36053,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Removes a watch from Watcher",
+        "summary": "Delete a watch",
+        "description": "When the watch is removed, the document representing the watch in the `.watches` index is gone and it will never be run again.\n\nDeleting a watch does not delete any watch execution records related to this watch from the watch history.\n\nIMPORTANT: Deleting a watch must be done by using only this API.\nDo not delete the watch directly from the `.watches` index using the Elasticsearch delete document API\nWhen Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the `.watches` index.",
         "operationId": "watcher-delete-watch",
         "parameters": [
           {
@@ -36081,8 +36104,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes",
-        "description": "For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.",
+        "summary": "Run a watch",
+        "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.",
         "operationId": "watcher-execute-watch",
         "parameters": [
           {
@@ -36105,8 +36128,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes",
-        "description": "For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.",
+        "summary": "Run a watch",
+        "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.",
         "operationId": "watcher-execute-watch-1",
         "parameters": [
           {
@@ -36131,8 +36154,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes",
-        "description": "For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.",
+        "summary": "Run a watch",
+        "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.",
         "operationId": "watcher-execute-watch-2",
         "parameters": [
           {
@@ -36152,8 +36175,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes",
-        "description": "For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.",
+        "summary": "Run a watch",
+        "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.",
         "operationId": "watcher-execute-watch-3",
         "parameters": [
           {
@@ -36175,7 +36198,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Retrieves stored watches",
+        "summary": "Query watches",
+        "description": "Get all registered watches in a paginated manner and optionally filter watches by a query.",
         "operationId": "watcher-query-watches",
         "requestBody": {
           "$ref": "#/components/requestBodies/watcher.query_watches"
@@ -36191,7 +36215,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Retrieves stored watches",
+        "summary": "Query watches",
+        "description": "Get all registered watches in a paginated manner and optionally filter watches by a query.",
         "operationId": "watcher-query-watches-1",
         "requestBody": {
           "$ref": "#/components/requestBodies/watcher.query_watches"
@@ -36209,7 +36234,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Starts Watcher if it is not already running",
+        "summary": "Start the watch service",
+        "description": "Start the Watcher service if it is not already running.",
         "operationId": "watcher-start",
         "responses": {
           "200": {
@@ -36230,7 +36256,7 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Retrieves the current Watcher metrics",
+        "summary": "Get Watcher statistics",
         "operationId": "watcher-stats",
         "parameters": [
           {
@@ -36253,7 +36279,7 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Retrieves the current Watcher metrics",
+        "summary": "Get Watcher statistics",
         "operationId": "watcher-stats-1",
         "parameters": [
           {
@@ -36279,7 +36305,8 @@
         "tags": [
           "watcher"
         ],
-        "summary": "Stops Watcher if it is running",
+        "summary": "Stop the watch service",
+        "description": "Stop the Watcher service if it is running.",
         "operationId": "watcher-stop",
         "responses": {
           "200": {
diff --git a/output/schema/schema.json b/output/schema/schema.json
index 5485e7136f..772ac0e6e8 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -20311,9 +20311,14 @@
           "stability": "stable"
         }
       },
-      "description": "Acknowledges a watch, manually throttling the execution of the watch's actions.",
+      "description": "Acknowledge a watch.\nAcknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-ack-watch.html",
       "name": "watcher.ack_watch",
+      "privileges": {
+        "cluster": [
+          "manage_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.ack_watch"
@@ -20349,9 +20354,16 @@
           "stability": "stable"
         }
       },
-      "description": "Activates a currently inactive watch.",
+      "description": "Activate a watch.\nA watch can be either active or inactive.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-activate-watch.html",
+      "extDocId": "watcher-works",
+      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/how-watcher-works.html",
       "name": "watcher.activate_watch",
+      "privileges": {
+        "cluster": [
+          "manage_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.activate_watch"
@@ -20380,9 +20392,16 @@
           "stability": "stable"
         }
       },
-      "description": "Deactivates a currently active watch.",
+      "description": "Deactivate a watch.\nA watch can be either active or inactive.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-deactivate-watch.html",
+      "extDocId": "watcher-works",
+      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/how-watcher-works.html",
       "name": "watcher.deactivate_watch",
+      "privileges": {
+        "cluster": [
+          "manage_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.deactivate_watch"
@@ -20411,9 +20430,14 @@
           "stability": "stable"
         }
       },
-      "description": "Removes a watch from Watcher.",
+      "description": "Delete a watch.\nWhen the watch is removed, the document representing the watch in the `.watches` index is gone and it will never be run again.\n\nDeleting a watch does not delete any watch execution records related to this watch from the watch history.\n\nIMPORTANT: Deleting a watch must be done by using only this API.\nDo not delete the watch directly from the `.watches` index using the Elasticsearch delete document API\nWhen Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the `.watches` index.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-delete-watch.html",
       "name": "watcher.delete_watch",
+      "privileges": {
+        "cluster": [
+          "manage_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.delete_watch"
@@ -20441,7 +20465,7 @@
           "stability": "stable"
         }
       },
-      "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.",
+      "description": "Run a watch.\nThis API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-execute-watch.html",
       "name": "watcher.execute_watch",
       "privileges": {
@@ -20516,9 +20540,14 @@
           "stability": "stable"
         }
       },
-      "description": "Retrieves a watch by its ID.",
+      "description": "Get a watch.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-get-watch.html",
       "name": "watcher.get_watch",
+      "privileges": {
+        "cluster": [
+          "monitor_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.get_watch"
@@ -20546,9 +20575,14 @@
           "stability": "stable"
         }
       },
-      "description": "Creates a new watch, or updates an existing one.",
+      "description": "Create or update a watch.\nWhen a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine.\nTypically for the `schedule` trigger, the scheduler is the trigger engine.\n\nIMPORTANT: You must use Kibana or this API to create a watch.\nDo not add a watch directly to the `.watches` index by using the Elasticsearch index API.\nIf Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.\n\nWhen you add a watch you can also define its initial active state by setting the *active* parameter.\n\nWhen Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.\nIf the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-put-watch.html",
       "name": "watcher.put_watch",
+      "privileges": {
+        "cluster": [
+          "manage_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.put_watch"
@@ -20581,9 +20615,14 @@
           "stability": "stable"
         }
       },
-      "description": "Retrieves stored watches.",
+      "description": "Query watches.\nGet all registered watches in a paginated manner and optionally filter watches by a query.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-query-watches.html",
       "name": "watcher.query_watches",
+      "privileges": {
+        "cluster": [
+          "monitor_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.query_watches"
@@ -20615,9 +20654,14 @@
           "stability": "stable"
         }
       },
-      "description": "Starts Watcher if it is not already running.",
+      "description": "Start the watch service.\nStart the Watcher service if it is not already running.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.html",
       "name": "watcher.start",
+      "privileges": {
+        "cluster": [
+          "manage_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.start"
@@ -20646,9 +20690,14 @@
           "stability": "stable"
         }
       },
-      "description": "Retrieves the current Watcher metrics.",
+      "description": "Get Watcher statistics.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stats.html",
       "name": "watcher.stats",
+      "privileges": {
+        "cluster": [
+          "monitor_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.stats"
@@ -20682,9 +20731,14 @@
           "stability": "stable"
         }
       },
-      "description": "Stops Watcher if it is running.",
+      "description": "Stop the watch service.\nStop the Watcher service if it is running.",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stop.html",
       "name": "watcher.stop",
+      "privileges": {
+        "cluster": [
+          "manage_watcher"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "watcher.stop"
@@ -216258,7 +216312,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Acknowledges a watch, manually throttling the execution of the watch's actions.",
+      "description": "Acknowledge a watch.\nAcknowledging a watch enables you to manually throttle the execution of the watch's actions.\n\nThe acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.\n\nIMPORTANT: If the specified watch is currently being executed, this API will return an error\nThe reason for this behavior is to prevent overwriting the watch status from a watch execution.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -216296,7 +216350,7 @@
         }
       ],
       "query": [],
-      "specLocation": "watcher/ack_watch/WatcherAckWatchRequest.ts#L23-L32"
+      "specLocation": "watcher/ack_watch/WatcherAckWatchRequest.ts#L23-L40"
     },
     {
       "kind": "response",
@@ -216330,7 +216384,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Activates a currently inactive watch.",
+      "description": "Activate a watch.\nA watch can be either active or inactive.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -216356,7 +216410,7 @@
         }
       ],
       "query": [],
-      "specLocation": "watcher/activate_watch/WatcherActivateWatchRequest.ts#L23-L31"
+      "specLocation": "watcher/activate_watch/WatcherActivateWatchRequest.ts#L23-L35"
     },
     {
       "kind": "response",
@@ -216390,7 +216444,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Deactivates a currently active watch.",
+      "description": "Deactivate a watch.\nA watch can be either active or inactive.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -216416,7 +216470,7 @@
         }
       ],
       "query": [],
-      "specLocation": "watcher/deactivate_watch/DeactivateWatchRequest.ts#L23-L31"
+      "specLocation": "watcher/deactivate_watch/DeactivateWatchRequest.ts#L23-L35"
     },
     {
       "kind": "response",
@@ -216450,7 +216504,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Removes a watch from Watcher.",
+      "description": "Delete a watch.\nWhen the watch is removed, the document representing the watch in the `.watches` index is gone and it will never be run again.\n\nDeleting a watch does not delete any watch execution records related to this watch from the watch history.\n\nIMPORTANT: Deleting a watch must be done by using only this API.\nDo not delete the watch directly from the `.watches` index using the Elasticsearch delete document API\nWhen Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the `.watches` index.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -216476,7 +216530,7 @@
         }
       ],
       "query": [],
-      "specLocation": "watcher/delete_watch/DeleteWatchRequest.ts#L23-L31"
+      "specLocation": "watcher/delete_watch/DeleteWatchRequest.ts#L23-L40"
     },
     {
       "kind": "response",
@@ -216638,7 +216692,7 @@
           }
         ]
       },
-      "description": "This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.",
+      "description": "Run a watch.\nThis API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.\n\nFor testing and debugging purposes, you also have fine-grained control on how the watch runs.\nYou can run the watch without running all of its actions or alternatively by simulating them.\nYou can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.\n\nYou can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.\nThis serves as great tool for testing and debugging your watches prior to adding them to Watcher.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -216678,7 +216732,7 @@
           }
         }
       ],
-      "specLocation": "watcher/execute_watch/WatcherExecuteWatchRequest.ts#L28-L79"
+      "specLocation": "watcher/execute_watch/WatcherExecuteWatchRequest.ts#L28-L86"
     },
     {
       "kind": "response",
@@ -216857,7 +216911,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Retrieves a watch by its ID.",
+      "description": "Get a watch.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -216883,7 +216937,7 @@
         }
       ],
       "query": [],
-      "specLocation": "watcher/get_watch/GetWatchRequest.ts#L23-L31"
+      "specLocation": "watcher/get_watch/GetWatchRequest.ts#L23-L33"
     },
     {
       "kind": "response",
@@ -217073,7 +217127,7 @@
           }
         ]
       },
-      "description": "Creates a new watch, or updates an existing one.",
+      "description": "Create or update a watch.\nWhen a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine.\nTypically for the `schedule` trigger, the scheduler is the trigger engine.\n\nIMPORTANT: You must use Kibana or this API to create a watch.\nDo not add a watch directly to the `.watches` index by using the Elasticsearch index API.\nIf Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.\n\nWhen you add a watch you can also define its initial active state by setting the *active* parameter.\n\nWhen Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.\nIf the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -217148,7 +217202,7 @@
           }
         }
       ],
-      "specLocation": "watcher/put_watch/WatcherPutWatchRequest.ts#L30-L53"
+      "specLocation": "watcher/put_watch/WatcherPutWatchRequest.ts#L30-L66"
     },
     {
       "kind": "response",
@@ -217290,7 +217344,7 @@
           }
         ]
       },
-      "description": "Retrieves stored watches.",
+      "description": "Query watches.\nGet all registered watches in a paginated manner and optionally filter watches by a query.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -217303,7 +217357,7 @@
       },
       "path": [],
       "query": [],
-      "specLocation": "watcher/query_watches/WatcherQueryWatchesRequest.ts#L25-L48"
+      "specLocation": "watcher/query_watches/WatcherQueryWatchesRequest.ts#L25-L51"
     },
     {
       "kind": "response",
@@ -217351,7 +217405,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Starts Watcher if it is not already running.",
+      "description": "Start the watch service.\nStart the Watcher service if it is not already running.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -217364,7 +217418,7 @@
       },
       "path": [],
       "query": [],
-      "specLocation": "watcher/start/WatcherStartRequest.ts#L22-L26"
+      "specLocation": "watcher/start/WatcherStartRequest.ts#L22-L29"
     },
     {
       "kind": "response",
@@ -217392,7 +217446,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Retrieves the current Watcher metrics.",
+      "description": "Get Watcher statistics.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -217474,7 +217528,7 @@
           }
         }
       ],
-      "specLocation": "watcher/stats/WatcherStatsRequest.ts#L23-L45"
+      "specLocation": "watcher/stats/WatcherStatsRequest.ts#L23-L47"
     },
     {
       "kind": "response",
@@ -217769,7 +217823,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Stops Watcher if it is running.",
+      "description": "Stop the watch service.\nStop the Watcher service if it is running.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -217782,7 +217836,7 @@
       },
       "path": [],
       "query": [],
-      "specLocation": "watcher/stop/WatcherStopRequest.ts#L22-L26"
+      "specLocation": "watcher/stop/WatcherStopRequest.ts#L22-L29"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index f1f5868f98..c5e2657a50 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -647,6 +647,7 @@ user-agent-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{br
 user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/user-profile.html
 verify-repository,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-verification
 voting-config-exclusions,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/voting-config-exclusions.html
+watcher-works,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/how-watcher-works.html
 watcher-api-ack-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-ack-watch.html
 watcher-api-activate-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-activate-watch.html
 watcher-api-deactivate-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-deactivate-watch.html
diff --git a/specification/watcher/ack_watch/WatcherAckWatchRequest.ts b/specification/watcher/ack_watch/WatcherAckWatchRequest.ts
index 4283e019c0..39dddff31a 100644
--- a/specification/watcher/ack_watch/WatcherAckWatchRequest.ts
+++ b/specification/watcher/ack_watch/WatcherAckWatchRequest.ts
@@ -21,8 +21,16 @@ import { RequestBase } from '@_types/Base'
 import { Name, Names } from '@_types/common'
 
 /**
+ * Acknowledge a watch.
+ * Acknowledging a watch enables you to manually throttle the execution of the watch's actions.
+ *
+ * The acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.
+ *
+ * IMPORTANT: If the specified watch is currently being executed, this API will return an error
+ * The reason for this behavior is to prevent overwriting the watch status from a watch execution.
  * @rest_spec_name watcher.ack_watch
  * @availability stack stability=stable
+ * @cluster_privileges manage_watcher
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts b/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts
index cbd1a80149..4a491a2c2d 100644
--- a/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts
+++ b/specification/watcher/activate_watch/WatcherActivateWatchRequest.ts
@@ -21,8 +21,12 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Activate a watch.
+ * A watch can be either active or inactive.
  * @rest_spec_name watcher.activate_watch
  * @availability stack stability=stable
+ * @cluster_privileges manage_watcher
+ * @ext_doc_id watcher-works
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts b/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts
index e509e8d82b..1c00ea404f 100644
--- a/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts
+++ b/specification/watcher/deactivate_watch/DeactivateWatchRequest.ts
@@ -21,8 +21,12 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Deactivate a watch.
+ * A watch can be either active or inactive.
  * @rest_spec_name watcher.deactivate_watch
  * @availability stack stability=stable
+ * @cluster_privileges manage_watcher
+ * @ext_doc_id watcher-works
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/watcher/delete_watch/DeleteWatchRequest.ts b/specification/watcher/delete_watch/DeleteWatchRequest.ts
index a51c92a8c1..dcc63e757e 100644
--- a/specification/watcher/delete_watch/DeleteWatchRequest.ts
+++ b/specification/watcher/delete_watch/DeleteWatchRequest.ts
@@ -21,8 +21,17 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Delete a watch.
+ * When the watch is removed, the document representing the watch in the `.watches` index is gone and it will never be run again.
+ *
+ * Deleting a watch does not delete any watch execution records related to this watch from the watch history.
+ *
+ * IMPORTANT: Deleting a watch must be done by using only this API.
+ * Do not delete the watch directly from the `.watches` index using the Elasticsearch delete document API
+ * When Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the `.watches` index.
  * @rest_spec_name watcher.delete_watch
  * @availability stack stability=stable
+ * @cluster_privileges manage_watcher
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts b/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts
index bb02e98dff..40d5ae3422 100644
--- a/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts
+++ b/specification/watcher/execute_watch/WatcherExecuteWatchRequest.ts
@@ -26,8 +26,15 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
+ * Run a watch.
  * This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.
- * For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can execute the watch without executing all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after execution.
+ *
+ * For testing and debugging purposes, you also have fine-grained control on how the watch runs.
+ * You can run the watch without running all of its actions or alternatively by simulating them.
+ * You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.
+ *
+ * You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline.
+ * This serves as great tool for testing and debugging your watches prior to adding them to Watcher.
  * @rest_spec_name watcher.execute_watch
  * @availability stack stability=stable
  * @cluster_privileges manage_watcher
diff --git a/specification/watcher/get_watch/GetWatchRequest.ts b/specification/watcher/get_watch/GetWatchRequest.ts
index 2057db4b1a..c6acb64013 100644
--- a/specification/watcher/get_watch/GetWatchRequest.ts
+++ b/specification/watcher/get_watch/GetWatchRequest.ts
@@ -21,8 +21,10 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Get a watch.
  * @rest_spec_name watcher.get_watch
  * @availability stack since=5.6.0 stability=stable
+ * @cluster_privileges monitor_watcher
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/watcher/put_watch/WatcherPutWatchRequest.ts b/specification/watcher/put_watch/WatcherPutWatchRequest.ts
index 49da8991e3..c5f474e0f7 100644
--- a/specification/watcher/put_watch/WatcherPutWatchRequest.ts
+++ b/specification/watcher/put_watch/WatcherPutWatchRequest.ts
@@ -28,8 +28,21 @@ import { long } from '@_types/Numeric'
 import { TransformContainer } from '@_types/Transform'
 
 /**
+ * Create or update a watch.
+ * When a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine.
+ * Typically for the `schedule` trigger, the scheduler is the trigger engine.
+ *
+ * IMPORTANT: You must use Kibana or this API to create a watch.
+ * Do not add a watch directly to the `.watches` index by using the Elasticsearch index API.
+ * If Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.
+ *
+ * When you add a watch you can also define its initial active state by setting the *active* parameter.
+ *
+ * When Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.
+ * If the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.
  * @rest_spec_name watcher.put_watch
  * @availability stack stability=stable
+ * @cluster_privileges manage_watcher
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts b/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts
index 97618a19c5..75c6880b6f 100644
--- a/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts
+++ b/specification/watcher/query_watches/WatcherQueryWatchesRequest.ts
@@ -23,8 +23,11 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
 import { Sort, SortResults } from '@_types/sort'
 
 /**
+ * Query watches.
+ * Get all registered watches in a paginated manner and optionally filter watches by a query.
  * @rest_spec_name watcher.query_watches
  * @availability stack since=7.11.0 stability=stable
+ * @cluster_privileges monitor_watcher
  */
 export interface Request extends RequestBase {
   body: {
diff --git a/specification/watcher/start/WatcherStartRequest.ts b/specification/watcher/start/WatcherStartRequest.ts
index 9cd0a34a7b..3d7528bd4b 100644
--- a/specification/watcher/start/WatcherStartRequest.ts
+++ b/specification/watcher/start/WatcherStartRequest.ts
@@ -20,7 +20,10 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Start the watch service.
+ * Start the Watcher service if it is not already running.
  * @rest_spec_name watcher.start
  * @availability stack stability=stable
+ * @cluster_privileges manage_watcher
  */
 export interface Request extends RequestBase {}
diff --git a/specification/watcher/stats/WatcherStatsRequest.ts b/specification/watcher/stats/WatcherStatsRequest.ts
index 17647a210b..b13be11185 100644
--- a/specification/watcher/stats/WatcherStatsRequest.ts
+++ b/specification/watcher/stats/WatcherStatsRequest.ts
@@ -21,8 +21,10 @@ import { RequestBase } from '@_types/Base'
 import { WatcherMetric } from './types'
 
 /**
+ * Get Watcher statistics.
  * @rest_spec_name watcher.stats
  * @availability stack since=5.5.0 stability=stable
+ * @cluster_privileges monitor_watcher
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/watcher/stop/WatcherStopRequest.ts b/specification/watcher/stop/WatcherStopRequest.ts
index 897a72f426..1560c387d0 100644
--- a/specification/watcher/stop/WatcherStopRequest.ts
+++ b/specification/watcher/stop/WatcherStopRequest.ts
@@ -20,7 +20,10 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Stop the watch service.
+ * Stop the Watcher service if it is running.
  * @rest_spec_name watcher.stop
  * @availability stack stability=stable
+ * @cluster_privileges manage_watcher
  */
 export interface Request extends RequestBase {}