Fix XML documentation spelling, grammar, and correctness issues across SDK (#1372)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Stephen Toub <stoub@microsoft.com>
Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>

src/ModelContextProtocol.Core/AIContentExtensions.cs

@@ -367,7 +367,7 @@ public static class AIContentExtensions
     /// </para>
     /// <para>
     /// Each <see cref="ResourceContents"/> object is converted using <see cref="ToAIContent(ResourceContents)"/>,
-    /// preserving the type-specific conversion logic: text resources become <see cref="TextContentBlock"/> objects and
+    /// preserving the type-specific conversion logic: text resources become <see cref="TextContent"/> objects and
     /// binary resources become <see cref="DataContent"/> objects.
     /// </para>
     /// </remarks>

src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs

@@ -772,7 +772,7 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
     /// <param name="response">The HTTP response containing the WWW-Authenticate header.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
     /// <returns>The resource metadata if the resource matches the server, otherwise throws an exception.</returns>
-    /// <exception cref="InvalidOperationException">Thrown when the response is not a 401, the metadata can't be fetched, or the resource URI doesn't match the server URL.</exception>
+    /// <exception cref="McpException">Thrown when the metadata can't be fetched or the resource URI doesn't match the server URL.</exception>
     private async Task<ProtectedResourceMetadata> ExtractProtectedResourceMetadata(HttpResponseMessage response, CancellationToken cancellationToken)
     {
         Uri resourceUri = _serverUrl;

src/ModelContextProtocol.Core/Authentication/ProtectedResourceMetadata.cs

@@ -4,8 +4,7 @@ using System.Text.Json.Serialization;
 namespace ModelContextProtocol.Authentication;
 
 /// <summary>
-/// Represents the resource metadata for OAuth authorization as defined in RFC 9396.
-/// Defined by <see href="https://datatracker.ietf.org/doc/rfc9728/">RFC 9728</see>.
+/// Represents the resource metadata for OAuth authorization as defined in <see href="https://datatracker.ietf.org/doc/rfc9728/">RFC 9728</see>.
 /// </summary>
 public sealed class ProtectedResourceMetadata
 {

src/ModelContextProtocol.Core/Client/HttpClientTransportOptions.cs

@@ -105,7 +105,7 @@ public sealed class HttpClientTransportOptions
     public bool OwnsSession { get; set; } = true;
 
     /// <summary>
-    /// Gets sor sets the authorization provider to use for authentication.
+    /// Gets or sets the authorization provider to use for authentication.
     /// </summary>
     public ClientOAuthOptions? OAuth { get; set; }
 
@@ -127,13 +127,13 @@ public sealed class HttpClientTransportOptions
     /// Gets or sets the default interval at which the client attempts reconnection after an SSE stream is disconnected.
     /// </summary>
     /// <remarks>
-    /// <p>
+    /// <para>
     /// The default value is 1 second.
-    /// </p>
-    /// <p>
+    /// </para>
+    /// <para>
     /// If the server sends a message specifying a different reconnection interval, that new value will be used for all
     /// subsequent reconnection attempts for that stream.
-    /// </p>
+    /// </para>
     /// </remarks>
     public TimeSpan DefaultReconnectionInterval { get; set; } = TimeSpan.FromSeconds(1);
 }

src/ModelContextProtocol.Core/Client/IClientTransport.cs

@@ -11,7 +11,7 @@ namespace ModelContextProtocol.Client;
 /// and servers, allowing different transport protocols to be used interchangeably.
 /// </para>
 /// <para>
-/// When creating an <see cref="McpClient"/>, <see cref="McpClient"/> is typically used, and is
+/// When creating an <see cref="McpClient"/>, <see cref="McpClient.CreateAsync"/> is typically used, and is
 /// provided with the <see cref="IClientTransport"/> based on expected server configuration.
 /// </para>
 /// </remarks>

src/ModelContextProtocol.Core/Client/McpClientHandlers.cs

@@ -14,7 +14,7 @@ namespace ModelContextProtocol.Client;
 /// <para>
 /// Each handler in this class corresponds to a specific client endpoint in the Model Context Protocol and
 /// is responsible for processing a particular type of message. The handlers are used to customize
-/// the behavior of the MCP server by providing implementations for the various protocol operations.
+/// the behavior of the MCP client by providing implementations for the various protocol operations.
 /// </para>
 /// <para>
 /// When a server sends a message to the client, the appropriate handler is invoked to process it
@@ -47,7 +47,7 @@ public sealed class McpClientHandlers
     /// Gets or sets the handler for <see cref="RequestMethods.RootsList"/> requests.
     /// </summary>
     /// <remarks>
-    /// This handler is invoked when a client sends a <see cref="RequestMethods.RootsList"/> request to retrieve available roots.
+    /// This handler is invoked when the server sends a <see cref="RequestMethods.RootsList"/> request to retrieve available roots.
     /// The handler receives request parameters and should return a <see cref="ListRootsResult"/> containing the collection of available roots.
     /// </remarks>
     public Func<ListRootsRequestParams?, CancellationToken, ValueTask<ListRootsResult>>? RootsHandler { get; set; }

src/ModelContextProtocol.Core/Client/McpClientOptions.cs

@@ -43,7 +43,7 @@ public sealed class McpClientOptions
     /// If non-<see langword="null"/>, this version will be sent to the server, and the handshake
     /// will fail if the version in the server's response does not match this version.
     /// If <see langword="null"/>, the client will request the latest version supported by the server
-    /// but will allow any supported version that the server advertizes in its response.
+    /// but will allow any supported version that the server advertises in its response.
     /// </para>
     /// </remarks>
     public string? ProtocolVersion { get; set; }

src/ModelContextProtocol.Core/Client/McpClientTool.cs

@@ -171,7 +171,7 @@ public sealed class McpClientTool : AIFunction
     /// </returns>
     /// <remarks>
     /// The base <see cref="AIFunction.InvokeAsync"/> method is overridden to invoke this <see cref="CallAsync"/> method.
-    /// The only difference in behavior is that <see cref="AIFunction.InvokeAsync"/> serializes the resulting <see cref="CallToolResult"/>"/>
+    /// The only difference in behavior is that <see cref="AIFunction.InvokeAsync"/> serializes the resulting <see cref="CallToolResult"/>
     /// such that the <see cref="object"/> returned is a <see cref="JsonElement"/> containing the serialized <see cref="CallToolResult"/>.
     /// This <see cref="CallAsync"/> method is intended to be called directly by user code, whereas the base <see cref="AIFunction.InvokeAsync"/>
     /// is intended to be used polymorphically via the base class, typically as part of an <see cref="IChatClient"/> operation.
@@ -247,7 +247,6 @@ public sealed class McpClientTool : AIFunction
     /// the value returned from this instance's <see cref="AITool.Name"/>.
     /// </para>
     /// </remarks>
-    /// <returns>A new instance of <see cref="McpClientTool"/> with the provided name.</returns>
     public McpClientTool WithName(string name) =>
         new(_client, ProtocolTool, JsonSerializerOptions, name, _description, _progress, _meta);
 

src/ModelContextProtocol.Core/Client/ResumeClientSessionOptions.cs

@@ -8,7 +8,7 @@ namespace ModelContextProtocol.Client;
 public sealed class ResumeClientSessionOptions
 {
     /// <summary>
-    /// Gets or sets the server capabilities that were negotiated during the original session setialization.
+    /// Gets or sets the server capabilities that were negotiated during the original session initialization.
     /// </summary>
     public required ServerCapabilities ServerCapabilities { get; set; }
 

src/ModelContextProtocol.Core/McpException.cs

@@ -3,7 +3,7 @@ using ModelContextProtocol.Protocol;
 namespace ModelContextProtocol;
 
 /// <summary>
-/// Represents an exception that is thrown when an Model Context Protocol (MCP) error occurs.
+/// Represents an exception that is thrown when a Model Context Protocol (MCP) error occurs.
 /// </summary>
 /// <remarks>
 /// The <see cref="Exception.Message"/> from a <see cref="McpException"/> might be propagated to the remote

src/ModelContextProtocol.Core/McpSession.Methods.cs

@@ -49,7 +49,7 @@ public abstract partial class McpSession : IAsyncDisposable
     /// <param name="method">The JSON-RPC method name to invoke.</param>
     /// <param name="parameters">The request parameters.</param>
     /// <param name="parametersTypeInfo">The type information for request parameter serialization.</param>
-    /// <param name="resultTypeInfo">The type information for request parameter deserialization.</param>
+    /// <param name="resultTypeInfo">The type information for result deserialization.</param>
     /// <param name="requestId">The request ID for the request.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized result.</returns>
@@ -138,7 +138,7 @@ public abstract partial class McpSession : IAsyncDisposable
     }
 
     /// <summary>
-    /// Sends a notification to the server with parameters.
+    /// Sends a notification to the connected session with parameters.
     /// </summary>
     /// <param name="method">The JSON-RPC method name to invoke.</param>
     /// <param name="parameters">The request parameters.</param>

src/ModelContextProtocol.Core/McpSession.cs

@@ -17,8 +17,8 @@ namespace ModelContextProtocol;
 /// </list>
 /// </para>
 /// <para>
-/// <see cref="McpSession"/> serves as the base interface for both <see cref="McpClient"/> and
-/// <see cref="McpServer"/> interfaces, providing the common functionality needed for MCP protocol
+/// <see cref="McpSession"/> serves as the base class for both <see cref="McpClient"/> and
+/// <see cref="McpServer"/>, providing the common functionality needed for MCP protocol
 /// communication. Most applications will use these more specific interfaces rather than working with
 /// <see cref="McpSession"/> directly.
 /// </para>
@@ -85,7 +85,7 @@ public abstract partial class McpSession : IAsyncDisposable
     /// <summary>Registers a handler to be invoked when a notification for the specified method is received.</summary>
     /// <param name="method">The notification method.</param>
     /// <param name="handler">The handler to be invoked.</param>
-    /// <returns>An <see cref="IDisposable"/> that will remove the registered handler when disposed.</returns>
+    /// <returns>An <see cref="IAsyncDisposable"/> that will remove the registered handler when disposed.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> or <paramref name="handler"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentException"><paramref name="method"/> is empty or composed entirely of whitespace.</exception>
     public abstract IAsyncDisposable RegisterNotificationHandler(string method, Func<JsonRpcNotification, CancellationToken, ValueTask> handler);

src/ModelContextProtocol.Core/McpSessionHandler.cs

@@ -47,7 +47,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
     /// Checks if the given protocol version supports priming events.
     /// </summary>
     /// <param name="protocolVersion">The protocol version to check.</param>
-    /// <returns>True if the protocol version supports resumability.</returns>
+    /// <returns>True if the protocol version supports priming events.</returns>
     /// <remarks>
     /// Priming events are only supported in protocol version &gt;= 2025-11-25.
     /// Older clients may crash when receiving SSE events with empty data.
@@ -463,7 +463,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
 
     /// <summary>
     /// Sends a JSON-RPC request to the server.
-    /// It is strongly recommended use the capability-specific methods instead of this one.
+    /// It is strongly recommended to use the capability-specific methods instead of this one.
     /// Use this method for custom requests or those not yet covered explicitly by the endpoint implementation.
     /// </summary>
     /// <param name="request">The JSON-RPC request to send.</param>

src/ModelContextProtocol.Core/NotificationHandlers.cs

@@ -152,7 +152,7 @@ internal sealed class NotificationHandlers
         /// by that handler are no longer in use and may be cleaned up. If <see cref="DisposeAsync"/> were to be invoked
         /// and its task awaited from within the invocation of the handler, however, that would result in deadlock, since
         /// the task wouldn't complete until the invocation completed, and the invocation wouldn't complete until the task
-        /// completed. To circument that, we track via an <see cref="AsyncLocal{Int32}"/> in-flight invocations. If
+        /// completed. To circumvent that, we track via an <see cref="AsyncLocal{Int32}"/> in-flight invocations. If
         /// <see cref="DisposeAsync"/> detects it's being invoked from within an invocation, it will avoid waiting. For
         /// simplicity, we don't require that it's the same handler.
         /// </remarks>

src/ModelContextProtocol.Core/ProcessHelper.cs

@@ -58,7 +58,7 @@ internal static class ProcessHelper
 #endif
 
         // wait until the process finishes exiting/getting killed. 
-        // We don't want to wait forever here because the task is already supposed to be dieing, we just want to give it long enough
+        // We don't want to wait forever here because the task is already supposed to be dying, we just want to give it long enough
         // to try and flush what it can and stop. If it cannot do that in a reasonable time frame then we will just ignore it.
         process.WaitForExit((int)timeout.TotalMilliseconds);
     }

src/ModelContextProtocol.Core/Protocol/BlobResourceContents.cs

@@ -32,13 +32,12 @@ public sealed class BlobResourceContents : ResourceContents
     private ReadOnlyMemory<byte>? _blob;
 
     /// <summary>
-    /// Creates an <see cref="BlobResourceContents"/> from raw data.
+    /// Creates a <see cref="BlobResourceContents"/> from raw data.
     /// </summary>
     /// <param name="bytes">The raw unencoded data.</param>
     /// <param name="uri">The URI of the blob resource.</param>
     /// <param name="mimeType">The optional MIME type of the data.</param>
     /// <returns>A new <see cref="BlobResourceContents"/> instance.</returns>
-    /// <exception cref="InvalidOperationException"></exception>
     public static BlobResourceContents FromBytes(ReadOnlyMemory<byte> bytes, string uri, string? mimeType = null)
     {
         return new(bytes, uri, mimeType);

src/ModelContextProtocol.Core/Protocol/CompletionsCapability.cs

@@ -22,7 +22,7 @@ namespace ModelContextProtocol.Protocol;
 /// </para>
 /// <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
+/// currently define additional properties for completions capabilities. Future versions of the
 /// specification might extend this capability with additional configuration options.
 /// </para>
 /// </remarks>

src/ModelContextProtocol.Core/Protocol/ContentBlock.cs

@@ -69,8 +69,10 @@ public abstract class ContentBlock
     /// <summary>
     /// Provides a <see cref="JsonConverter"/> for <see cref="ContentBlock"/>.
     /// </summary>
-    /// Provides a polymorphic converter for the <see cref="ContentBlock"/> class that doesn't  require
+    /// <remarks>
+    /// Provides a polymorphic converter for the <see cref="ContentBlock"/> class that doesn't require
     /// setting <see cref="JsonSerializerOptions.AllowOutOfOrderMetadataProperties"/> explicitly.
+    /// </remarks>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public sealed class Converter : JsonConverter<ContentBlock>
     {

src/ModelContextProtocol.Core/Protocol/ElicitRequestParams.cs

@@ -182,10 +182,12 @@ public sealed class ElicitRequestParams : RequestParams
         public string? Description { get; set; }
 
         /// <summary>
-        /// Provides a <see cref="JsonConverter"/> for <see cref="ResourceContents"/>.
+        /// Provides a <see cref="JsonConverter"/> for <see cref="PrimitiveSchemaDefinition"/>.
         /// </summary>
+        /// <remarks>
         /// Provides a polymorphic converter for the <see cref="PrimitiveSchemaDefinition"/> class that doesn't require
         /// setting <see cref="JsonSerializerOptions.AllowOutOfOrderMetadataProperties"/> explicitly.
+        /// </remarks>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public sealed class Converter : JsonConverter<PrimitiveSchemaDefinition>
         {

src/ModelContextProtocol.Core/Protocol/ElicitResult.cs

@@ -37,7 +37,7 @@ public sealed class ElicitResult : Result
     /// Gets a value that indicates whether the elicitation was accepted by the user.
     /// </summary>
     /// <remarks>
-    /// If <see langword="true"/>, it indicates that the elicitation request completed successfully and value of <see cref="Content"/> has been populated with a value.
+    /// If <see langword="true"/>, it indicates that the elicitation request completed successfully and the value of <see cref="Content"/> has been populated with a value.
     /// </remarks>
     [JsonIgnore]
     public bool IsAccepted => string.Equals(Action, "accept", StringComparison.OrdinalIgnoreCase);
@@ -122,7 +122,7 @@ public sealed class ElicitResult<T> : Result
     /// Gets a value that indicates whether the elicitation was accepted by the user.
     /// </summary>
     /// <remarks>
-    /// If <see langword="true"/>, it indicates that the elicitation request completed successfully and value of <see cref="Content"/> has been populated with a value.
+    /// If <see langword="true"/>, it indicates that the elicitation request completed successfully and the value of <see cref="Content"/> has been populated with a value.
     /// </remarks>
     public bool IsAccepted => string.Equals(Action, "accept", StringComparison.OrdinalIgnoreCase);