chore: better descriptions

Author: shortcuts

specs/ingestion/paths/push.yml

@@ -1,6 +1,11 @@
 post:
-  summary: Push a `batch` request payload through the Pipeline
-  description: Push a `batch` request payload through the Pipeline. You can check the status of your request with the observability endpoints.
+  summary: Pushes records through the Pipeline, directly to an index
+  description: >
+    Pushes records through the Pipeline, directly to an index. You can make the call synchronous by providing the `watch` parameter,
+    for asynchronous calls, you can use the observability endpoints and/or debugger dashboard to see the status of your task.
+
+    This method is similar to `pushTask`, but requires an `indexName` instead of a `taskID`. If zero or many tasks are found,
+    an error will be returned.
   operationId: push
   x-acl:
     - addObject
@@ -14,7 +19,6 @@ post:
     - $ref: '../../common/parameters.yml#/IndexName'
     - $ref: '../common/parameters.yml#/watch'
   requestBody:
-    description: Request body of a Search API `batch` request that will be pushed in the Connectors pipeline.
     content:
       application/json:
         schema:

specs/ingestion/paths/tasks/v2/pushTask.yml

@@ -1,8 +1,12 @@
 post:
   tags:
     - tasks
-  summary: Push a `batch` request payload through the Pipeline
-  description: Push a `batch` request payload through the Pipeline. You can check the status of task pushes with the observability endpoints.
+  summary: Pushes records through the Pipeline, directly to an index
+  description: >
+    Pushes records through the Pipeline, directly to an index. You can make the call synchronous by providing the `watch` parameter,
+    for asynchronous calls, you can use the observability endpoints and/or debugger dashboard to see the status of your task.
+
+    This method is similar to `push`, but requires a `taskID` instead of a `indexName`, which is useful when many `destinations` target the same `indexName`.
   operationId: pushTask
   x-acl:
     - addObject
@@ -16,7 +20,6 @@ post:
     - $ref: '../../../common/parameters.yml#/pathTaskID'
     - $ref: '../../../common/parameters.yml#/watch'
   requestBody:
-    description: Request body of a Search API `batch` request that will be pushed in the Connectors pipeline.
     content:
       application/json:
         schema: