Core Protocol docs edit pass (#1032)

Author: gewarren

src/ModelContextProtocol.Core/Protocol/Annotations.cs

@@ -22,7 +22,7 @@ public sealed class Annotations
     /// </summary>
     /// <remarks>
     /// The value is a floating-point number between 0 and 1, where 0 represents the lowest priority
-    /// 1 represents highest priority.
+    /// and 1 represents the highest priority.
     /// </remarks>
     [JsonPropertyName("priority")]
     public float? Priority { get; set; }
@@ -31,8 +31,8 @@ public sealed class Annotations
     /// Gets or sets the moment the resource was last modified.
     /// </summary>
     /// <remarks>
-    /// The corresponding JSON should be an ISO 8601 formatted string (e.g., \"2025-01-12T15:00:58Z\").
-    /// Examples: last activity timestamp in an open file, timestamp when the resource was attached, etc.
+    /// The corresponding JSON should be an ISO 8601 formatted string (for example, \"2025-01-12T15:00:58Z\").
+    /// Examples of when the resource was last modified include last activity in an open file or when the resource was attached.
     /// </remarks>
     [JsonPropertyName("lastModified")]
     public DateTimeOffset? LastModified { get; set; }

src/ModelContextProtocol.Core/Protocol/Argument.cs

@@ -21,7 +21,7 @@ public sealed class Argument
     /// Gets or sets the current partial text value for which completion suggestions are requested.
     /// </summary>
     /// <remarks>
-    /// This represents the text that has been entered so far and for which completion
+    /// This property represents the text that has been entered so far and for which completion
     /// options should be generated.
     /// </remarks>
     [JsonPropertyName("value")]

src/ModelContextProtocol.Core/Protocol/CallToolResult.cs

@@ -36,17 +36,19 @@ public sealed class CallToolResult : Result
     public JsonNode? StructuredContent { get; set; }
 
     /// <summary>
-    /// Gets or sets an indication of whether the tool call was unsuccessful.
+    /// Gets or sets a value that indicates whether the tool call was unsuccessful.
     /// </summary>
+    /// <value>
+    /// <see langword="true"/> to signify that the tool execution failed; <see langword="false"/> if it was successful.
+    /// </value>
     /// <remarks>
     /// <para>
-    /// When set to <see langword="true"/>, it signifies that the tool execution failed.
     /// Tool execution errors (including input validation errors, API failures, and business logic errors)
     /// are reported with this property set to <see langword="true"/> and details in the <see cref="Content"/>
     /// property, rather than as protocol-level errors.
     /// </para>
     /// <para>
-    /// This allows language models to receive detailed error feedback and potentially self-correct
+    /// This design allows language models to receive detailed error feedback and potentially self-correct
     /// in subsequent requests. For example, if a date parameter is in the wrong format or out of range,
     /// the error message in <see cref="Content"/> can explain the issue, enabling the model to retry
     /// with corrected parameters.

src/ModelContextProtocol.Core/Protocol/CancelledNotificationParams.cs

@@ -17,7 +17,7 @@ public sealed class CancelledNotificationParams : NotificationParams
     /// Gets or sets the ID of the request to cancel.
     /// </summary>
     /// <remarks>
-    /// This must match the ID of an in-flight request that the sender wishes to cancel.
+    /// This value must match the ID of an in-flight request that the sender wishes to cancel.
     /// </remarks>
     [JsonPropertyName("requestId")]
     public required RequestId RequestId { get; set; }
@@ -27,4 +27,4 @@ public sealed class CancelledNotificationParams : NotificationParams
     /// </summary>
     [JsonPropertyName("reason")]
     public string? Reason { get; set; }
-}
+}

src/ModelContextProtocol.Core/Protocol/ClientCapabilities.cs

@@ -6,7 +6,7 @@
 namespace ModelContextProtocol.Protocol;
 
 /// <summary>
-/// Represents the capabilities that a client may support.
+/// Represents the capabilities that a client supports.
 /// </summary>
 /// <remarks>
 /// <para>
@@ -24,13 +24,13 @@ public sealed class ClientCapabilities
     /// </summary>
     /// <remarks>
     /// <para>
-    /// The <see cref="Experimental"/> dictionary allows clients to advertise support for features that are not yet 
-    /// standardized in the Model Context Protocol specification. This extension mechanism enables 
+    /// The <see cref="Experimental"/> dictionary allows clients to advertise support for features that are not yet
+    /// standardized in the Model Context Protocol specification. This extension mechanism enables
     /// future protocol enhancements while maintaining backward compatibility.
     /// </para>
     /// <para>
-    /// Values in this dictionary are implementation-specific and should be coordinated between client 
-    /// and server implementations. Servers should not assume the presence of any experimental capability 
+    /// Values in this dictionary are implementation-specific and should be coordinated between client
+    /// and server implementations. Servers should not assume the presence of any experimental capability
     /// without checking for it first.
     /// </para>
     /// </remarks>
@@ -42,7 +42,7 @@ public sealed class ClientCapabilities
     /// </summary>
     /// <remarks>
     /// <para>
-    /// When <see cref="Roots"/> is non-<see langword="null"/>, the client indicates that it can respond to 
+    /// When <see cref="Roots"/> is non-<see langword="null"/>, the client indicates that it can respond to
     /// server requests for listing root URIs. Root URIs serve as entry points for resource navigation in the protocol.
     /// </para>
     /// <para>
@@ -54,14 +54,14 @@ public sealed class ClientCapabilities
     public RootsCapability? Roots { get; set; }
 
     /// <summary>
-    /// Gets or sets the client's sampling capability, which indicates whether the client 
+    /// Gets or sets the client's sampling capability, which indicates whether the client
     /// supports issuing requests to an LLM on behalf of the server.
     /// </summary>
     [JsonPropertyName("sampling")]
     public SamplingCapability? Sampling { get; set; }
 
     /// <summary>
-    /// Gets or sets the client's elicitation capability, which indicates whether the client 
+    /// Gets or sets the client's elicitation capability, which indicates whether the client
     /// supports elicitation of additional information from the user on behalf of the server.
     /// </summary>
     [JsonPropertyName("elicitation")]
@@ -70,7 +70,7 @@ public sealed class ClientCapabilities
     /// <summary>Gets or sets notification handlers to register with the client.</summary>
     /// <remarks>
     /// <para>
-    /// When constructed, the client will enumerate these handlers once, which may contain multiple handlers per notification method key.
+    /// When constructed, the client will enumerate these handlers, which may contain multiple handlers per notification method key, once.
     /// The client will not re-enumerate the sequence after initialization.
     /// </para>
     /// <para>
@@ -80,12 +80,12 @@ public sealed class ClientCapabilities
     /// </para>
     /// <para>
     /// Handlers provided via <see cref="NotificationHandlers"/> will be registered with the client for the lifetime of the client.
-    /// For transient handlers, <see cref="McpSession.RegisterNotificationHandler"/> may be used to register a handler that can
+    /// For transient handlers, <see cref="McpSession.RegisterNotificationHandler"/> can be used to register a handler that can
     /// then be unregistered by disposing of the <see cref="IAsyncDisposable"/> returned from the method.
     /// </para>
     /// </remarks>
     [JsonIgnore]
     [Obsolete($"Use {nameof(McpClientOptions.Handlers.NotificationHandlers)} instead. This member will be removed in a subsequent release.")] // See: https://github.com/modelcontextprotocol/csharp-sdk/issues/774
     [EditorBrowsable(EditorBrowsableState.Never)]
     public IEnumerable<KeyValuePair<string, Func<JsonRpcNotification, CancellationToken, ValueTask>>>? NotificationHandlers { get; set; }
-}
+}

src/ModelContextProtocol.Core/Protocol/Completion.cs

@@ -16,7 +16,7 @@ public sealed class Completion
     /// <remarks>
     /// This collection contains the actual text strings to be presented to users as completion suggestions.
     /// The array will be empty if no suggestions are available for the current input.
-    /// Per the specification, this should not exceed 100 items.
+    /// Per the specification, this collection should not exceed 100 items.
     /// </remarks>
     [JsonPropertyName("values")]
     public IList<string> Values { get; set; } = [];
@@ -25,13 +25,13 @@ public sealed class Completion
     /// Gets or sets the total number of completion options available.
     /// </summary>
     /// <remarks>
-    /// This can exceed the number of values actually sent in the response.
+    /// This value can exceed the number of values actually sent in the response.
     /// </remarks>
     [JsonPropertyName("total")]
     public int? Total { get; set; }
 
     /// <summary>
-    /// Gets or sets an indicator as to whether there are additional completion options beyond 
+    /// Gets or sets a value that indicates whether there are additional completion options beyond
     /// those provided in the current response, even if the exact total is unknown.
     /// </summary>
     [JsonPropertyName("hasMore")]

src/ModelContextProtocol.Core/Protocol/CompletionsCapability.cs

@@ -23,7 +23,7 @@ namespace ModelContextProtocol.Protocol;
 /// <para>
 /// This class is intentionally empty as the Model Context Protocol specification does not
 /// currently define additional properties for sampling capabilities. Future versions of the
-/// specification may extend this capability with additional configuration options.
+/// specification might extend this capability with additional configuration options.
 /// </para>
 /// </remarks>
 public sealed class CompletionsCapability
@@ -40,4 +40,4 @@ public sealed class CompletionsCapability
     [Obsolete($"Use {nameof(McpServerOptions.Handlers.CompleteHandler)} instead. This member will be removed in a subsequent release.")] // See: https://github.com/modelcontextprotocol/csharp-sdk/issues/774
     [EditorBrowsable(EditorBrowsableState.Never)]
     public McpRequestHandler<CompleteRequestParams, CompleteResult>? CompleteHandler { get; set; }
-}
+}

src/ModelContextProtocol.Core/Protocol/ContentBlock.cs

@@ -35,8 +35,11 @@ private protected ContentBlock()
     /// <summary>
     /// When overridden in a derived class, gets the type of content.
     /// </summary>
+    /// <value>
+    /// The type of content. Valid values include "image", "audio", "text", "resource", "resource_link", "tool_use", and "tool_result".
+    /// </value>
     /// <remarks>
-    /// This determines the structure of the content object. Valid values include "image", "audio", "text", "resource", "resource_link", "tool_use", and "tool_result".
+    /// This value determines the structure of the content object.
     /// </remarks>
     [JsonPropertyName("type")]
     public abstract string Type { get; }
@@ -381,9 +384,7 @@ public sealed class ImageContentBlock : ContentBlock
     /// Gets or sets the MIME type (or "media type") of the content, specifying the format of the data.
     /// </summary>
     /// <remarks>
-    /// <para>
     /// Common values include "image/png" and "image/jpeg".
-    /// </para>
     /// </remarks>
     [JsonPropertyName("mimeType")]
     public required string MimeType { get; set; }
@@ -405,9 +406,7 @@ public sealed class AudioContentBlock : ContentBlock
     /// Gets or sets the MIME type (or "media type") of the content, specifying the format of the data.
     /// </summary>
     /// <remarks>
-    /// <para>
     /// Common values include "audio/wav" and "audio/mp3".
-    /// </para>
     /// </remarks>
     [JsonPropertyName("mimeType")]
     public required string MimeType { get; set; }
@@ -427,7 +426,7 @@ public sealed class EmbeddedResourceBlock : ContentBlock
     /// </summary>
     /// <remarks>
     /// <para>
-    /// Resources can be either text-based (<see cref="TextResourceContents"/>) or 
+    /// Resources can be either text-based (<see cref="TextResourceContents"/>) or
     /// binary (<see cref="BlobResourceContents"/>), allowing for flexible data representation.
     /// Each resource has a URI that can be used for identification and retrieval.
     /// </para>
@@ -463,7 +462,7 @@ public sealed class ResourceLinkBlock : ContentBlock
     /// </summary>
     /// <remarks>
     /// <para>
-    /// This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.
+    /// This description can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.
     /// </para>
     /// <para>
     /// The description should provide clear context about the resource's content, format, and purpose.
@@ -487,7 +486,7 @@ public sealed class ResourceLinkBlock : ContentBlock
     /// "image/png" for PNG images, and "application/json" for JSON data.
     /// </para>
     /// <para>
-    /// This property may be <see langword="null"/> if the MIME type is unknown or not applicable for the resource.
+    /// This property can be <see langword="null"/> if the MIME type is unknown or not applicable for the resource.
     /// </para>
     /// </remarks>
     [JsonPropertyName("mimeType")]
@@ -497,7 +496,7 @@ public sealed class ResourceLinkBlock : ContentBlock
     /// Gets or sets the size of the raw resource content (before base64 encoding), in bytes, if known.
     /// </summary>
     /// <remarks>
-    /// This can be used by applications to display file sizes and estimate context window usage.
+    /// This value can be used by applications to display file sizes and estimate context window usage.
     /// </remarks>
     [JsonPropertyName("size")]
     public long? Size { get; set; }
@@ -541,7 +540,7 @@ public sealed class ToolResultContentBlock : ContentBlock
     /// Gets or sets the ID of the tool use this result corresponds to.
     /// </summary>
     /// <remarks>
-    /// This must match the ID from a previous <see cref="ToolUseContentBlock"/>.
+    /// This value must match the ID from a previous <see cref="ToolUseContentBlock"/>.
     /// </remarks>
     [JsonPropertyName("toolUseId")]
     public required string ToolUseId { get; set; }
@@ -550,7 +549,7 @@ public sealed class ToolResultContentBlock : ContentBlock
     /// Gets or sets the unstructured result content of the tool use.
     /// </summary>
     /// <remarks>
-    /// This has the same format as CallToolResult.Content and can include text, images,
+    /// This value has the same format as CallToolResult.Content and can include text, images,
     /// audio, resource links, and embedded resources.
     /// </remarks>
     [JsonPropertyName("content")]
@@ -560,17 +559,19 @@ public sealed class ToolResultContentBlock : ContentBlock
     /// Gets or sets an optional structured result object.
     /// </summary>
     /// <remarks>
-    /// If the tool defined an outputSchema, this should conform to that schema.
+    /// If the tool defined an outputSchema, this object should conform to that schema.
     /// </remarks>
     [JsonPropertyName("structuredContent")]
     public JsonElement? StructuredContent { get; set; }
 
     /// <summary>
-    /// Gets or sets whether the tool use resulted in an error.
+    /// Gets or sets a value that indicates whether the tool use resulted in an error.
     /// </summary>
+    /// <value>
+    /// <see langword="true"/> if the tool use resulted in an error; <see langword="false"/> if it succeeded. The default is <see langword="false"/>.
+    /// </value>
     /// <remarks>
-    /// If true, the content typically describes the error that occurred.
-    /// Default: false
+    /// If <see langword="true"/>, the content typically describes the error that occurred.
     /// </remarks>
     [JsonPropertyName("isError")]
     public bool? IsError { get; set; }

src/ModelContextProtocol.Core/Protocol/ContextInclusion.cs

@@ -12,20 +12,20 @@ namespace ModelContextProtocol.Protocol;
 /// <para>
 /// <see cref="ContextInclusion"/>, and in particular <see cref="ThisServer"/> and <see cref="AllServers"/>, are deprecated.
 /// Servers should only use these values if the client declares <see cref="ClientCapabilities.Sampling"/> with
-/// <see cref="SamplingCapability.Context"/> set. These values may be removed in future spec releases.
+/// <see cref="SamplingCapability.Context"/> set. These values might be removed in future spec releases.
 /// </para>
 /// </remarks>
 [JsonConverter(typeof(JsonStringEnumConverter<ContextInclusion>))]
 public enum ContextInclusion
 {
     /// <summary>
-    /// Indicates that no context should be included.
+    /// No context should be included.
     /// </summary>
     [JsonStringEnumMemberName("none")]
     None,
 
     /// <summary>
-    /// Indicates that context from the server that sent the request should be included.
+    /// Context from the server that sent the request should be included.
     /// </summary>
     /// <remarks>
     /// This value is soft-deprecated. Servers should only use this value if the client
@@ -35,7 +35,7 @@ public enum ContextInclusion
     ThisServer,
 
     /// <summary>
-    /// Indicates that context from all servers that the client is connected to should be included.
+    /// Context from all servers that the client is connected to should be included.
     /// </summary>
     /// <remarks>
     /// This value is soft-deprecated. Servers should only use this value if the client