diff --git a/spec/src/main/java/io/a2a/spec/A2AMethods.java b/spec/src/main/java/io/a2a/spec/A2AMethods.java
index 0ffdf6e30..636b0d81b 100644
--- a/spec/src/main/java/io/a2a/spec/A2AMethods.java
+++ b/spec/src/main/java/io/a2a/spec/A2AMethods.java
@@ -1,17 +1,31 @@
 
 package io.a2a.spec;
 
+/**
+ * Constants defining the A2A protocol method names.
+ */
 public interface A2AMethods {
+    /** Method name for canceling a task. */
     String CANCEL_TASK_METHOD = "CancelTask";
+    /** Method name for deleting task push notification configuration. */
     String DELETE_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "DeleteTaskPushNotificationConfig";
+    /** Method name for getting extended agent card information. */
     String GET_EXTENDED_AGENT_CARD_METHOD = "GetExtendedAgentCard";
+    /** Method name for getting a task. */
     String GET_TASK_METHOD = "GetTask";
+    /** Method name for getting task push notification configuration. */
     String GET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "GetTaskPushNotificationConfig";
+    /** Method name for listing tasks. */
     String LIST_TASK_METHOD = "ListTasks";
+    /** Method name for listing task push notification configurations. */
     String LIST_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "ListTaskPushNotificationConfig";
+    /** Method name for sending a message. */
     String SEND_MESSAGE_METHOD = "SendMessage";
+    /** Method name for sending a streaming message. */
     String SEND_STREAMING_MESSAGE_METHOD = "SendStreamingMessage";
+    /** Method name for setting task push notification configuration. */
     String SET_TASK_PUSH_NOTIFICATION_CONFIG_METHOD = "SetTaskPushNotificationConfig";
+    /** Method name for subscribing to task events. */
     String SUBSCRIBE_TO_TASK_METHOD = "SubscribeToTask";
 
 }
diff --git a/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java b/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java
index a69c9a4ad..fb72a00e9 100644
--- a/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/APIKeySecurityScheme.java
@@ -29,6 +29,9 @@ public record APIKeySecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param location the location where the API key is sent (required)
+     * @param name the name of the API key parameter (required)
+     * @param description a human-readable description (optional)
      * @throws IllegalArgumentException if location or name is null
      */
     public APIKeySecurityScheme {
diff --git a/spec/src/main/java/io/a2a/spec/DataPart.java b/spec/src/main/java/io/a2a/spec/DataPart.java
index 163225429..55157a205 100644
--- a/spec/src/main/java/io/a2a/spec/DataPart.java
+++ b/spec/src/main/java/io/a2a/spec/DataPart.java
@@ -49,6 +49,7 @@ public record DataPart(Map<String, Object> data) implements Part<Map<String, Obj
     /**
      * Compact constructor with validation and defensive copying.
      *
+     * @param data the structured data map (required, defensively copied for immutability)
      * @throws IllegalArgumentException if data is null
      */
     public DataPart {
diff --git a/spec/src/main/java/io/a2a/spec/FilePart.java b/spec/src/main/java/io/a2a/spec/FilePart.java
index 79b63fe64..ac18393c6 100644
--- a/spec/src/main/java/io/a2a/spec/FilePart.java
+++ b/spec/src/main/java/io/a2a/spec/FilePart.java
@@ -49,6 +49,7 @@ public record FilePart(FileContent file) implements Part<FileContent> {
     /**
      * Compact constructor with validation.
      *
+     * @param file the file content (required, either FileWithBytes or FileWithUri)
      * @throws IllegalArgumentException if file is null
      */
     public FilePart {
diff --git a/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java b/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java
index 54858562f..7e4a9a968 100644
--- a/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/HTTPAuthSecurityScheme.java
@@ -47,6 +47,9 @@ public record HTTPAuthSecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param bearerFormat the bearer token format (optional)
+     * @param scheme the authentication scheme (required)
+     * @param description the scheme description (optional)
      * @throws IllegalArgumentException if scheme is null
      */
     public HTTPAuthSecurityScheme {
diff --git a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java
index f339afd88..3c69f7d6e 100644
--- a/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java
+++ b/spec/src/main/java/io/a2a/spec/ListTaskPushNotificationConfigParams.java
@@ -18,9 +18,11 @@ public record ListTaskPushNotificationConfigParams(String id, int pageSize, Stri
     /**
      * Compact constructor for validation.
      * Validates that required parameters are not null.
-     *
      * @param id the task identifier
+     * @param pageSize the maximum number of items to return per page
+     * @param pageToken the pagination token for the next page
      * @param tenant the tenant identifier
+     * @throws IllegalArgumentException if id or tenant is null
      */
     public ListTaskPushNotificationConfigParams {
         Assert.checkNotNullParam("id", id);
diff --git a/spec/src/main/java/io/a2a/spec/Message.java b/spec/src/main/java/io/a2a/spec/Message.java
index 9606cd15d..4383b1e02 100644
--- a/spec/src/main/java/io/a2a/spec/Message.java
+++ b/spec/src/main/java/io/a2a/spec/Message.java
@@ -47,6 +47,14 @@ public record Message(Role role, List<Part<?>> parts,
     /**
      * Compact constructor with validation and defensive copying.
      *
+     * @param role the role of the message sender (user or agent)
+     * @param parts the content parts of the message (text, file, or data)
+     * @param messageId the unique identifier for this message
+     * @param contextId the conversation context identifier
+     * @param taskId the task identifier this message is associated with
+     * @param referenceTaskIds list of reference task identifiers
+     * @param metadata additional metadata for the message
+     * @param extensions list of protocol extensions used in this message
      * @throws IllegalArgumentException if role, parts, or messageId is null, or if parts is empty
      */
     public Message {
@@ -80,6 +88,7 @@ public static Builder builder() {
      * Creates a new Builder initialized with values from an existing Message.
      *
      * @param message the Message to copy values from
+     * @return a new Builder instance initialized with the message's values
      */
     public static Builder builder(Message message) {
         return new Builder(message);
diff --git a/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java b/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java
index f3179cc23..58d969de2 100644
--- a/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/OAuth2SecurityScheme.java
@@ -33,6 +33,9 @@ public record OAuth2SecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param flows the OAuth 2.0 flow configuration (required)
+     * @param description optional description of the security scheme
+     * @param oauth2MetadataUrl optional URL to OAuth 2.0 metadata (RFC 8414)
      * @throws IllegalArgumentException if flows is null
      */
     public OAuth2SecurityScheme {
diff --git a/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java b/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java
index e7dfcfab3..6f73770ce 100644
--- a/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java
+++ b/spec/src/main/java/io/a2a/spec/OpenIdConnectSecurityScheme.java
@@ -41,6 +41,8 @@ public record OpenIdConnectSecurityScheme(
     /**
      * Compact constructor with validation.
      *
+     * @param openIdConnectUrl URL to the OpenID Connect Discovery document (required)
+     * @param description optional description of the security scheme
      * @throws IllegalArgumentException if openIdConnectUrl is null
      */
     public OpenIdConnectSecurityScheme {
diff --git a/spec/src/main/java/io/a2a/spec/Task.java b/spec/src/main/java/io/a2a/spec/Task.java
index b9e37aabb..24336dcd9 100644
--- a/spec/src/main/java/io/a2a/spec/Task.java
+++ b/spec/src/main/java/io/a2a/spec/Task.java
@@ -59,6 +59,12 @@ public record Task(
     /**
      * Compact constructor with validation and defensive copying.
      *
+     * @param id the task identifier
+     * @param contextId the context identifier
+     * @param status the task status
+     * @param artifacts the list of artifacts produced by the task
+     * @param history the message history for this task
+     * @param metadata additional metadata for the task
      * @throws IllegalArgumentException if id, contextId, or status is null
      */
     public Task {
@@ -91,6 +97,7 @@ public static Builder builder() {
      * by copying all fields and then selectively updating specific values.
      *
      * @param task the Task to copy values from
+     * @return a new Builder instance initialized with the task's values
      */
     public static Builder builder(Task task) {
         return new Builder(task);
diff --git a/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java b/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java
index b8d468b78..b2ca5265e 100644
--- a/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java
+++ b/spec/src/main/java/io/a2a/spec/TaskArtifactUpdateEvent.java
@@ -55,6 +55,12 @@ public record TaskArtifactUpdateEvent(
     /**
      * Compact constructor with validation.
      *
+     * @param taskId the task identifier (required)
+     * @param artifact the artifact being updated (required)
+     * @param contextId the context identifier (required)
+     * @param append whether to append to existing artifact (optional)
+     * @param lastChunk whether this is the final chunk (optional)
+     * @param metadata additional metadata (optional)
      * @throws IllegalArgumentException if taskId, artifact, or contextId is null
      */
     public TaskArtifactUpdateEvent {
diff --git a/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java b/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java
index 8dc872bba..09e3bf39a 100644
--- a/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java
+++ b/spec/src/main/java/io/a2a/spec/TaskStatusUpdateEvent.java
@@ -30,6 +30,12 @@ public record TaskStatusUpdateEvent(
 
     /**
      * Compact constructor with validation.
+     * @param taskId the task identifier (required)
+     * @param status the task status (required)
+     * @param contextId the context identifier (required)
+     * @param isFinal whether this is a final status
+     * @param metadata additional metadata (optional)
+     * @throws IllegalArgumentException if taskId, status, or contextId is null
      */
     public TaskStatusUpdateEvent {
         Assert.checkNotNullParam("taskId", taskId);
diff --git a/spec/src/main/java/io/a2a/spec/TextPart.java b/spec/src/main/java/io/a2a/spec/TextPart.java
index 4ab51f217..8fa4e8e83 100644
--- a/spec/src/main/java/io/a2a/spec/TextPart.java
+++ b/spec/src/main/java/io/a2a/spec/TextPart.java
@@ -37,6 +37,7 @@ public record TextPart(String text) implements Part<String> {
     /**
      * Compact constructor with validation.
      *
+     * @param text the text content (required, must not be null)
      * @throws IllegalArgumentException if text is null
      */
     public TextPart {
diff --git a/spec/src/main/java/io/a2a/util/package-info.java b/spec/src/main/java/io/a2a/util/package-info.java
index 769e16337..78adaa656 100644
--- a/spec/src/main/java/io/a2a/util/package-info.java
+++ b/spec/src/main/java/io/a2a/util/package-info.java
@@ -1,3 +1,6 @@
+/**
+ * Utility classes and helpers for the A2A Java SDK.
+ */
 @NullMarked
 package io.a2a.util;