docs(aws): add descriptions (#686)

* docs(aws): add descriptions

* Apply suggestions from code review

* Apply suggestions from code review

---------

Co-authored-by: Will Russell <wrussell@kestra.io>

Author: aj-emerich

src/main/java/io/kestra/plugin/aws/athena/Query.java

@@ -48,11 +48,9 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Query an Amazon Athena table.",
+    title = "Run an Athena query and fetch results",
     description = """
-        The query will wait for completion, except if fetchMode is set to `NONE`, and will output converted rows.
-        Row conversion is based on the types listed in [Athena Data Types](https://docs.aws.amazon.com/athena/latest/ug/data-types.html).
-        Complex data types like array, map, and struct will be converted to a string."""
+        Executes an Athena SQL query and waits for completion unless fetchType is NONE. Converts primitive columns to native types and stores results according to fetchType; default STORE writes an ION file to internal storage. skipHeader defaults to true to drop the header row; complex Athena types (array/map/struct) are returned as strings."""
 )
 @Plugin(
     examples = {
@@ -129,36 +127,45 @@
     }
 )
 public class Query extends AbstractConnection implements RunnableTask<Query.QueryOutput> {
-    @Schema(title = "Athena catalog.")
+    @Schema(
+        title = "Athena catalog",
+        description = "Optional catalog name; use default if omitted."
+    )
     private Property<String> catalog;
 
-    @Schema(title = "Athena database.")
+    @Schema(
+        title = "Athena database",
+        description = "Target database for the query."
+    )
     @NotNull
     private Property<String> database;
 
     @Schema(
-        title = "Athena output location.",
-        description = "The query results will be stored in this output location. Must be an existing S3 bucket."
+        title = "Athena output location",
+        description = "Existing S3 URI where Athena writes result files (required by service)."
     )
     @NotNull
     private Property<String> outputLocation;
 
-    @Schema(title = "Athena SQL query.")
+    @Schema(
+        title = "Athena SQL query",
+        description = "SQL statement executed by Athena."
+    )
     @NotNull
     private Property<String> query;
 
     @Schema(
-        title = "The way you want to store the data.",
-        description = "FETCH_ONE outputs the first row, "
-            + "FETCH outputs all the rows, "
-            + "STORE stores all rows in a file, "
-            + "NONE does nothing — in this case, the task submits the query without waiting for its completion."
+        title = "Fetch strategy",
+        description = "Default STORE writes all rows to internal storage; FETCH loads all rows into memory; FETCH_ONE returns the first row; NONE submits without waiting."
     )
     @NotNull
     @Builder.Default
     private Property<FetchType> fetchType = Property.ofValue(FetchType.STORE);
 
-    @Schema(title = "Whether to skip the first row which is usually the header.")
+    @Schema(
+        title = "Skip header row",
+        description = "If true (default), drop the first returned row, which is usually the column header."
+    )
     @NotNull
     @Builder.Default
     private Property<Boolean> skipHeader = Property.ofValue(true);
@@ -356,29 +363,33 @@ private Object mapCell(ColumnInfo columnInfo, Datum datum) {
     @Getter
     public static class QueryOutput implements Output {
 
-        @Schema(title = "The query execution identifier.")
+        @Schema(
+            title = "Query execution ID",
+            description = "Identifier returned by StartQueryExecution."
+        )
         private String queryExecutionId;
 
         @Schema(
-            title = "List containing the fetched data.",
-            description = "Only populated if `fetchType=FETCH`."
+            title = "Rows",
+            description = "All rows when fetchType is FETCH."
         )
         private List<Object> rows;
 
         @Schema(
-            title = "Map containing the first row of fetched data.",
-            description = "Only populated if `fetchType=FETCH_ONE`."
+            title = "First row",
+            description = "Single row when fetchType is FETCH_ONE."
         )
         private Map<String, Object> row;
 
         @Schema(
-            title = "The URI of stored data.",
-            description = "Only populated if `fetchType=STORE`."
+            title = "Stored data URI",
+            description = "Internal storage URI when fetchType is STORE."
         )
         private URI uri;
 
         @Schema(
-            title = "The size of the fetched rows."
+            title = "Fetched row count",
+            description = "Number of rows returned or stored."
         )
         private Long size;
     }

src/main/java/io/kestra/plugin/aws/auth/EksToken.java

@@ -32,7 +32,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Fetch an OAuth access token for an AWS EKS cluster."
+    title = "Generate a presigned EKS authentication token",
+    description = "Builds a short-lived `k8s-aws-v1` token for a given EKS cluster by presigning STS GetCallerIdentity. Requires region and cluster name; expirationDuration defaults to 600s."
 )
 @Plugin(
     examples = {
@@ -55,11 +56,17 @@
 )
 public class EksToken extends AbstractConnection implements RunnableTask<EksToken.Output> {
 
-    @Schema(title = "EKS cluster name.")
+    @Schema(
+        title = "EKS cluster name",
+        description = "Cluster identifier passed in x-k8s-aws-id when presigning."
+    )
     @NotNull
     private Property<String> clusterName;
 
-    @Schema(title = "Token expiration duration in seconds")
+    @Schema(
+        title = "Token TTL (seconds)",
+        description = "Lifetime of the presigned URL; default 600 seconds."
+    )
     @NotNull
     @Builder.Default
     private Property<Long> expirationDuration = Property.ofValue(600L);
@@ -123,7 +130,10 @@ public static URI getStsRegionalEndpointUri(RunContext runContext, Region awsReg
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
         @NotNull
-        @Schema(title = "An OAuth access token for the current user.")
+        @Schema(
+            title = "EKS auth token",
+            description = "Bearer token formatted as k8s-aws-v1.<base64url>; encrypted in outputs when supported."
+        )
         private final Token token;
     }
 
@@ -136,6 +146,10 @@ public static class Token {
         )
         EncryptedString tokenValue;
 
+        @Schema(
+            title = "Token expiration time",
+            description = "Exact UTC expiration timestamp derived from the provided TTL."
+        )
         Instant expirationTime;
     }
-}
+}

src/main/java/io/kestra/plugin/aws/cli/AwsCLI.java

@@ -34,7 +34,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Run AWS CLI commands."
+    title = "Execute AWS CLI commands in a task",
+    description = "Runs one or more AWS CLI statements inside the configured task runner (default Docker with amazon/aws-cli). Exports rendered AWS credentials/region to the process env, honors stsRole* fields, and sets AWS_DEFAULT_OUTPUT to outputFormat (default json). Use outputFiles to persist generated files."
 )
 @Plugin(
     examples = {
@@ -113,13 +114,15 @@ public class AwsCLI extends AbstractConnection implements RunnableTask<ScriptOut
     private static final String DEFAULT_IMAGE = "amazon/aws-cli";
 
     @Schema(
-        title = "The AWS commands to run."
+        title = "AWS CLI commands",
+        description = "Shell fragments executed in order with /bin/sh -c; include aws ... and any needed piped tooling."
     )
     @NotNull
     protected List<String> commands;
 
     @Schema(
-        title = "Additional environment variables for the current process."
+        title = "Extra environment variables",
+        description = "Merged into the process environment alongside AWS credentials and AWS_DEFAULT_OUTPUT."
     )
     @PluginProperty(
         additionalProperties = String.class,
@@ -128,28 +131,33 @@ public class AwsCLI extends AbstractConnection implements RunnableTask<ScriptOut
     protected Map<String, String> env;
 
     @Schema(
-        title = "Deprecated, use 'taskRunner' instead"
+        title = "Deprecated Docker options",
+        description = "Use taskRunner instead; retained for backward compatibility."
     )
     @PluginProperty
     @Deprecated
     private DockerOptions docker;
 
     @Schema(
-        title = "The task runner to use.",
-        description = "Task runners are provided by plugins, each have their own properties."
+        title = "Task runner",
+        description = "Runner implementation for executing the CLI; defaults to Docker runner."
     )
     @PluginProperty
     @Builder.Default
     @Valid
     private TaskRunner<?> taskRunner = Docker.instance();
 
-    @Schema(title = "The task runner container image, only used if the task runner is container-based.")
+    @Schema(
+        title = "Container image",
+        description = "Image used when the runner is container-based; default amazon/aws-cli."
+    )
     @PluginProperty(dynamic = true)
     @Builder.Default
     private String containerImage = DEFAULT_IMAGE;
 
     @Schema(
-        title = "Expected output format for AWS commands (can be overridden with --format parameter)."
+        title = "AWS CLI output format",
+        description = "Sets AWS_DEFAULT_OUTPUT; default json. CLI flags still take precedence."
     )
     @PluginProperty
     @Builder.Default

src/main/java/io/kestra/plugin/aws/cloudformation/AbstractCloudFormation.java

@@ -23,15 +23,21 @@
 public abstract class AbstractCloudFormation extends AbstractConnection {
 
     @NotNull
-    @Schema(title = "The name of the stack.")
+    @Schema(
+        title = "Stack name",
+        description = "CloudFormation stack identifier used by create, update, and delete operations."
+    )
     protected Property<String> stackName;
 
     @Builder.Default
-    @Schema(title = "Whether to wait for the stack operation to complete.")
+    @Schema(
+        title = "Wait for completion",
+        description = "When true (default), block until the stack reaches a terminal state for the requested operation."
+    )
     protected Property<Boolean> waitForCompletion = Property.of(true);
 
     protected CloudFormationClient cfClient(final RunContext runContext) throws IllegalVariableEvaluationException {
         final AwsClientConfig clientConfig = awsClientConfig(runContext);
         return ConnectionUtils.configureSyncClient(clientConfig, CloudFormationClient.builder()).build();
     }
-}
+}

src/main/java/io/kestra/plugin/aws/cloudformation/Create.java

@@ -25,7 +25,8 @@
 @Getter
 @NoArgsConstructor
 @Schema(
-    title = "Create or update a CloudFormation stack."
+    title = "Create or update a CloudFormation stack",
+    description = "Creates the stack if it does not exist, otherwise issues an update. Can wait for terminal status when waitForCompletion is true (default). Uses templateBody and optional parameters; only succeeds when template changes are allowed."
 )
 @Plugin(
     examples = {
@@ -62,10 +63,16 @@
 )
 public class Create extends AbstractCloudFormation implements RunnableTask<Create.Output> {
 
-    @Schema(title = "The structure that contains the stack template.")
+    @Schema(
+        title = "Template body",
+        description = "YAML or JSON template content."
+    )
     private Property<String> templateBody;
 
-    @Schema(title = "A list of Parameter structures for the stack.")
+    @Schema(
+        title = "Template parameters",
+        description = "Key-value map rendered into CloudFormation parameters."
+    )
     private Property<Map<String, String>> parameters;
 
     @Override
@@ -153,13 +160,21 @@ private List<Parameter> mapToParameters(RunContext runContext, Map<String, Strin
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
 
-        @Schema(title = "The unique stack ID.")
+        @Schema(
+            title = "Stack ID",
+            description = "Unique identifier returned by CloudFormation."
+        )
         private final String stackId;
 
-        @Schema(title = "The name of the stack.") 
+        @Schema(
+            title = "Stack name"
+        ) 
         private final String stackName;
 
-        @Schema(title = "A map of the stack's outputs.")
+        @Schema(
+            title = "Stack outputs",
+            description = "Outputs returned by the deployed stack."
+        )
         private final Map<String, String> stackOutputs;
     }
-}
+}

src/main/java/io/kestra/plugin/aws/cloudformation/Delete.java

@@ -17,7 +17,10 @@
 @EqualsAndHashCode
 @Getter
 @NoArgsConstructor
-@Schema(title = "Delete a CloudFormation stack.")
+@Schema(
+    title = "Delete a CloudFormation stack",
+    description = "Triggers stack deletion and optionally waits for DELETE_COMPLETE when waitForCompletion is true (default). Fails fast if the stack cannot be deleted."
+)
 @Plugin(
     examples = {
         @Example(
@@ -70,4 +73,4 @@ public VoidOutput run(RunContext runContext) throws Exception {
 
         return null;
     }
-}
+}

src/main/java/io/kestra/plugin/aws/cloudwatch/AbstractCloudWatch.java

@@ -4,6 +4,7 @@
 import io.kestra.core.runners.RunContext;
 import io.kestra.plugin.aws.AbstractConnection;
 import io.kestra.plugin.aws.ConnectionUtils;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -16,6 +17,10 @@
 @EqualsAndHashCode
 @Getter
 @NoArgsConstructor
+@Schema(
+    title = "Shared CloudWatch connection",
+    description = "Provides CloudWatchClient configuration via standard AWS connection settings."
+)
 abstract class AbstractCloudWatch extends AbstractConnection {
     protected CloudWatchClient client(final RunContext runContext) throws IllegalVariableEvaluationException {
         final AwsClientConfig clientConfig = awsClientConfig(runContext);

src/main/java/io/kestra/plugin/aws/cloudwatch/CloudWatchLogs.java

@@ -4,6 +4,7 @@
 import io.kestra.core.runners.RunContext;
 import io.kestra.plugin.aws.AbstractConnection;
 import io.kestra.plugin.aws.ConnectionUtils;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -16,6 +17,10 @@
 @EqualsAndHashCode
 @Getter
 @NoArgsConstructor
+@Schema(
+    title = "Create a CloudWatch Logs client",
+    description = "Helper task for obtaining a configured CloudWatchLogsClient using standard AWS connection properties."
+)
 public class CloudWatchLogs extends AbstractConnection {
 
     /**