diff --git a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
index 648be8b4b..d5fbc886b 100644
--- a/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
+++ b/mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
@@ -35,6 +35,7 @@
  * @author Surbhi Bansal
  * @author Anurag Pant
  * @author Dariusz Jędrzejczyk
+ * @author Yanming Zhou
  */
 public final class McpSchema {
 
@@ -596,6 +597,14 @@ public record ClientCapabilities( // @formatter:off
 		@JsonIgnoreProperties(ignoreUnknown = true)
 		public record RootCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
 
+			/**
+			 * @deprecated Use {@link #builder()} instead.
+			 */
+			@Deprecated
+			public RootCapabilities {
+
+			}
+
 			public static Builder builder() {
 				return new Builder();
 			}
@@ -822,6 +831,14 @@ public record LoggingCapabilities() {
 		@JsonIgnoreProperties(ignoreUnknown = true)
 		public record PromptCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
 
+			/**
+			 * @deprecated Use {@link #builder()} instead.
+			 */
+			@Deprecated
+			public PromptCapabilities {
+
+			}
+
 			public static Builder builder() {
 				return new Builder();
 			}
@@ -854,6 +871,14 @@ public PromptCapabilities build() {
 		public record ResourceCapabilities(@JsonProperty("subscribe") Boolean subscribe,
 				@JsonProperty("listChanged") Boolean listChanged) {
 
+			/**
+			 * @deprecated Use {@link #builder()} instead.
+			 */
+			@Deprecated
+			public ResourceCapabilities {
+
+			}
+
 			public static Builder builder() {
 				return new Builder();
 			}
@@ -891,6 +916,14 @@ public ResourceCapabilities build() {
 		@JsonIgnoreProperties(ignoreUnknown = true)
 		public record ToolCapabilities(@JsonProperty("listChanged") Boolean listChanged) {
 
+			/**
+			 * @deprecated Use {@link #builder()} instead.
+			 */
+			@Deprecated
+			public ToolCapabilities {
+
+			}
+
 			public static Builder builder() {
 				return new Builder();
 			}
@@ -1120,6 +1153,10 @@ public record Icon( // @formatter:off
 		@JsonProperty("sizes") List<String> sizes,
 		@JsonProperty("theme") String theme) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(String)} instead.
+		 */
+		@Deprecated
 		public Icon {
 			Assert.notNull(src, "Icon src must not be null");
 		}
@@ -2357,6 +2394,10 @@ public record PromptMessage( // @formatter:off
 		@JsonProperty("role") Role role,
 		@JsonProperty("content") Content content) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(Role, Content)}.
+		 */
+		@Deprecated
 		public PromptMessage {
 			Assert.notNull(role, "role must not be null");
 			Assert.notNull(content, "content must not be null");
@@ -2703,6 +2744,14 @@ public record JsonSchema( // @formatter:off
 		@JsonProperty("$defs") Map<String, Object> defs,
 		@JsonProperty("definitions") Map<String, Object> definitions) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
+		public JsonSchema {
+
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}
@@ -2779,6 +2828,14 @@ public record ToolAnnotations( // @formatter:off
 		@JsonProperty("openWorldHint") Boolean openWorldHint,
 		@JsonProperty("returnDirect") Boolean returnDirect) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
+		public ToolAnnotations {
+
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}
@@ -3207,6 +3264,10 @@ public record CallToolResult( // @formatter:off
 		@JsonProperty("structuredContent") Object structuredContent,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Result { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public CallToolResult {
 			Assert.notNull(content, "content must not be null");
 		}
@@ -3387,6 +3448,14 @@ public record ModelPreferences( // @formatter:off
 		@JsonProperty("speedPriority") Double speedPriority,
 		@JsonProperty("intelligencePriority") Double intelligencePriority) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
+		public ModelPreferences {
+
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}
@@ -3475,6 +3544,10 @@ public record SamplingMessage( // @formatter:off
 		@JsonProperty("role") Role role,
 		@JsonProperty("content") Content content) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(Role, Content)} instead.
+		 */
+		@Deprecated
 		public SamplingMessage {
 			Assert.notNull(role, "role must not be null");
 			Assert.notNull(content, "content must not be null");
@@ -3561,6 +3634,10 @@ public record CreateMessageRequest( // @formatter:off
 		@JsonProperty("metadata") Map<String, Object> metadata,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Request { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(List, int)} instead.
+		 */
+		@Deprecated
 		public CreateMessageRequest {
 			Assert.notNull(messages, "messages must not be null");
 			Assert.notNull(maxTokens, "maxTokens must not be null");
@@ -3803,6 +3880,10 @@ public static StopReason of(String value) {
 		}
 
 		// backwards compatibility constructor
+		/**
+		 * @deprecated Use {@link #builder(Role, Content, String)} instead.
+		 */
+		@Deprecated
 		public CreateMessageResult(Role role, Content content, String model, StopReason stopReason) {
 			this(role, content, model, stopReason, null);
 		}
@@ -3951,6 +4032,10 @@ public record LegacyTitledEnumSchema( // @formatter:off
 		@JsonProperty("enumNames") List<String> enumNames,
 		@JsonProperty("default") String defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public LegacyTitledEnumSchema {
 			Assert.notNull(enumValues, "enumValues must not be null");
 		}
@@ -4042,6 +4127,10 @@ public record UntitledSingleSelectEnumSchema( // @formatter:off
 		@JsonProperty("enum") List<String> enumValues,
 		@JsonProperty("default") String defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public UntitledSingleSelectEnumSchema {
 			Assert.notNull(enumValues, "enumValues must not be null");
 		}
@@ -4120,6 +4209,10 @@ public record TitledSingleSelectEnumSchema( // @formatter:off
 		@JsonProperty("oneOf") List<EnumSchemaOption> oneOf,
 		@JsonProperty("default") String defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public TitledSingleSelectEnumSchema {
 			Assert.notEmpty(oneOf, "oneOf must not be empty");
 		}
@@ -4192,6 +4285,10 @@ public TitledSingleSelectEnumSchema build() {
 	public record UntitledMultiSelectItems( // @formatter:off
 		@JsonProperty("enum") List<String> enumValues) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public UntitledMultiSelectItems {
 			Assert.notNull(enumValues, "enumValues must not be null");
 		}
@@ -4252,6 +4349,10 @@ public record UntitledMultiSelectEnumSchema( // @formatter:off
 		@JsonProperty("maxItems") Integer maxItems,
 		@JsonProperty("default") List<String> defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public UntitledMultiSelectEnumSchema {
 			Assert.notNull(items, "items must not be null");
 		}
@@ -4341,6 +4442,10 @@ public UntitledMultiSelectEnumSchema build() {
 	public record TitledMultiSelectItems( // @formatter:off
 		@JsonProperty("anyOf") List<EnumSchemaOption> anyOf) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public TitledMultiSelectItems {
 			Assert.notNull(anyOf, "anyOf must not be null");
 		}
@@ -4396,6 +4501,10 @@ public record TitledMultiSelectEnumSchema( // @formatter:off
 		@JsonProperty("maxItems") Integer maxItems,
 		@JsonProperty("default") List<String> defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public TitledMultiSelectEnumSchema {
 			Assert.notNull(items, "items must not be null");
 		}
@@ -4487,6 +4596,14 @@ public record BooleanSchema( // @formatter:off
 		@JsonProperty("description") String description,
 		@JsonProperty("default") Boolean defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
+		public BooleanSchema {
+
+		}
+
 		@JsonProperty("type")
 		public String type() {
 			return "boolean";
@@ -4551,6 +4668,10 @@ public record NumberSchema( // @formatter:off
 		@JsonProperty("maximum") Number maximum,
 		@JsonProperty("default") Number defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public NumberSchema {
 			Assert.notNull(type, "type must not be null");
 		}
@@ -4633,6 +4754,14 @@ public record StringSchema( // @formatter:off
 		@JsonProperty("format") String format,
 		@JsonProperty("default") String defaultValue) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
+		public StringSchema {
+
+		}
+
 		@JsonProperty("type")
 		public String type() {
 			return "string";
@@ -4799,6 +4928,10 @@ public record ElicitFormRequest( // @formatter:off
 
 		public static final String MODE = "form";
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public ElicitFormRequest {
 			Assert.notNull(message, "message must not be null");
 			Assert.notNull(requestedSchema, "requestedSchema must not be null");
@@ -4924,6 +5057,10 @@ public record ElicitUrlRequest( // @formatter:off
 
 		public static final String MODE = "url";
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public ElicitUrlRequest {
 			Assert.notNull(message, "message must not be null");
 			Assert.notNull(url, "url must not be null");
@@ -5048,6 +5185,10 @@ public enum Action {
 		} // @formatter:on
 
 		// backwards compatibility constructor
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public ElicitResult(Action action, Map<String, Object> content) {
 			this(action, content, null);
 		}
@@ -5204,6 +5345,10 @@ public record ProgressNotification( // @formatter:off
 		@JsonProperty("message") String message,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Notification { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public ProgressNotification {
 			Assert.notNull(progressToken, "progressToken must not be null");
 			Assert.notNull(progress, "progress must not be null");
@@ -5361,6 +5506,10 @@ static LoggingMessageNotification fromJson(@JsonProperty("level") LoggingLevel l
 		}
 
 		// backwards compatibility constructor
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public LoggingMessageNotification(LoggingLevel level, String logger, String data) {
 			this(level, logger, data, null);
 		}
@@ -5558,6 +5707,10 @@ public record PromptReference( // @formatter:off
 
 		public static final String TYPE = "ref/prompt";
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
 		public PromptReference {
 			Assert.hasText(name, "name must not be null or empty");
 			if (type != null && !TYPE.equals(type)) {
@@ -5582,6 +5735,9 @@ public PromptReference(String type, String name) {
 			this(type, name, null);
 		}
 
+		/**
+		 * @deprecated Use {@link #builder(String)} instead.
+		 */
 		public PromptReference(String name) {
 			this(TYPE, name, null);
 		}
@@ -5689,6 +5845,10 @@ public record CompleteRequest( // @formatter:off
 		@JsonProperty("_meta") Map<String, Object> meta,
 		@JsonProperty("context") CompleteContext context) implements Request { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(CompleteReference, CompleteArgument)} instead.
+		 */
+		@Deprecated
 		public CompleteRequest {
 			Assert.notNull(ref, "ref must not be null");
 			Assert.notNull(argument, "argument must not be null");
@@ -5777,6 +5937,14 @@ public record CompleteArgument(@JsonProperty("name") String name, @JsonProperty(
 		@JsonIgnoreProperties(ignoreUnknown = true)
 		public record CompleteContext(@JsonProperty("arguments") Map<String, String> arguments) {
 
+			/**
+			 * @deprecated Use {@link #builder()} instead.
+			 */
+			@Deprecated
+			public CompleteContext {
+
+			}
+
 			public static Builder builder() {
 				return new Builder();
 			}
@@ -5907,6 +6075,10 @@ public record TextContent( // @formatter:off
 		@JsonProperty("text") String text,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Annotated, Content { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(String)} instead.
+		 */
+		@Deprecated
 		public TextContent {
 			Assert.notNull(text, "text must not be null");
 		}
@@ -5982,6 +6154,10 @@ public record ImageContent( // @formatter:off
 		@JsonProperty("mimeType") String mimeType,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Annotated, Content { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(String, String)} instead.
+		 */
+		@Deprecated
 		public ImageContent {
 			Assert.notNull(data, "data must not be null");
 			Assert.notNull(mimeType, "mimeType must not be null");
@@ -6067,6 +6243,10 @@ public record AudioContent( // @formatter:off
 		@JsonProperty("mimeType") String mimeType,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Annotated, Content { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(String, String)} instead.
+		 */
+		@Deprecated
 		public AudioContent {
 			Assert.notNull(data, "data must not be null");
 			Assert.notNull(mimeType, "mimeType must not be null");
@@ -6153,6 +6333,10 @@ public record EmbeddedResource( // @formatter:off
 		@JsonProperty("resource") ResourceContents resource,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Annotated, Content { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(ResourceContents)} instead.
+		 */
+		@Deprecated
 		public EmbeddedResource {
 			Assert.notNull(resource, "resource must not be null");
 		}
@@ -6238,6 +6422,14 @@ public record ResourceLink( // @formatter:off
 		@JsonProperty("annotations") Annotations annotations,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Content, ResourceContent { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder()} instead.
+		 */
+		@Deprecated
+		public ResourceLink {
+
+		}
+
 		public static Builder builder() {
 			return new Builder();
 		}
@@ -6331,6 +6523,10 @@ public record Root( // @formatter:off
 		@JsonProperty("name") String name,
 		@JsonProperty("_meta") Map<String, Object> meta) { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(String)} instead.
+		 */
+		@Deprecated
 		public Root {
 			Assert.notNull(uri, "uri must not be null");
 		}
@@ -6345,6 +6541,10 @@ static Root fromJson(@JsonProperty("uri") String uri, @JsonProperty("name") Stri
 			return new Root(uri, name, meta);
 		}
 
+		/**
+		 * @deprecated Use {@link #builder(String)} instead.
+		 */
+		@Deprecated
 		public Root(String uri, String name) {
 			this(uri, name, null);
 		}
@@ -6402,6 +6602,10 @@ public record ListRootsResult( // @formatter:off
 		@JsonProperty("nextCursor") String nextCursor,
 		@JsonProperty("_meta") Map<String, Object> meta) implements Result { // @formatter:on
 
+		/**
+		 * @deprecated Use {@link #builder(List)} instead.
+		 */
+		@Deprecated
 		public ListRootsResult {
 			Assert.notNull(roots, "roots must not be null");
 		}