[DOCS] Edit Watcher summaries

Author: lcawl

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

specification/_doc_ids/table.csv

@@ -646,6 +646,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

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: {

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: {

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: {

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: {

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

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: {

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: {

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: {