Add validation and error signaling guidance to MCP tool XML docs (#1275)

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

Author: Copilot

src/ModelContextProtocol.Core/McpException.cs

@@ -12,6 +12,11 @@ namespace ModelContextProtocol;
 ///
 /// This exception type can be thrown by MCP tools or tool call filters to propagate detailed error messages
 /// from <see cref="Exception.Message"/> when a tool execution fails via a <see cref="CallToolResult"/>.
+/// This includes input validation errors, business logic errors, or any other failure that the model should
+/// be informed about. For example, if a required field is missing or a value is out of range, throwing an
+/// <see cref="McpException"/> with a descriptive message allows the model to understand the issue and
+/// potentially self-correct in a subsequent request.
+///
 /// For non-tool calls, this exception controls the message propagated via a <see cref="JsonRpcError"/>.
 ///
 /// <see cref="McpProtocolException"/> is a derived type that can be used to also specify the

src/ModelContextProtocol.Core/Protocol/CallToolResult.cs

@@ -14,6 +14,13 @@ namespace ModelContextProtocol.Protocol;
 /// and potentially self-correct in subsequent requests.
 /// </para>
 /// <para>
+/// To return a validation or business-logic error from a tool method, either throw an <see cref="McpException"/>
+/// (whose <see cref="Exception.Message"/> will be included in the error result), or declare the tool's return type
+/// as <see cref="CallToolResult"/> so it can be returned directly with <see cref="IsError"/> set to <see langword="true"/>
+/// and details in <see cref="Content"/>. Using <see cref="CallToolResult"/> as the return type gives the tool full control
+/// over both success and error responses.
+/// </para>
+/// <para>
 /// Protocol-level errors (such as unknown tool names, malformed requests that fail schema validation,
 /// or server errors) should be reported as MCP protocol error responses using <see cref="McpErrorCode"/>.
 /// </para>

src/ModelContextProtocol.Core/Protocol/Tool.cs

@@ -31,7 +31,15 @@ public sealed class Tool : IBaseMetadata
     /// </para>
     /// <para>
     /// The description is typically presented to AI models to help them determine when
-    /// and how to use the tool based on user requests.
+    /// and how to use the tool based on user requests. A well-written description significantly
+    /// reduces incorrect tool invocations. Include information about what the tool does, any
+    /// constraints or prerequisites, and what it returns.
+    /// </para>
+    /// <para>
+    /// Similarly, individual parameter descriptions (provided via <see cref="System.ComponentModel.DescriptionAttribute"/>
+    /// on tool method parameters) are important for guiding the model to supply correct argument values.
+    /// Descriptions should document expected formats, valid value ranges, and any other constraints
+    /// the model should be aware of.
     /// </para>
     /// </remarks>
     [JsonPropertyName("description")]

src/ModelContextProtocol.Core/Server/McpServerTool.cs

@@ -90,6 +90,26 @@ namespace ModelContextProtocol.Server;
 /// to provide data to the method.
 /// </para>
 /// <para>
+/// The tool method is responsible for validating its own input arguments (e.g., checking required fields, value ranges, string lengths, or
+/// any other business rules). Data annotations such as <c>RequiredAttribute</c> and
+/// <c>MaxLengthAttribute</c> on parameter types influence the generated JSON schema exposed
+/// to clients, but they are not enforced at runtime by the SDK. Validation should be performed explicitly within the tool method.
+/// </para>
+/// <para>
+/// To signal an error (including validation failures) back to the client, either throw an <see cref="McpException"/>
+/// or return a <see cref="CallToolResult"/> with <see cref="CallToolResult.IsError"/> set to <see langword="true"/>.
+/// When a tool throws an <see cref="McpException"/>, its <see cref="Exception.Message"/> is included in the error result
+/// sent to the client. Throwing any other exception type also results in an error <see cref="CallToolResult"/>, but with
+/// a generic error message (to avoid leaking sensitive information). Alternatively, a tool can declare a return type of
+/// <see cref="CallToolResult"/> to have full control over both success and error responses.
+/// </para>
+/// <para>
+/// It is important to provide clear <see cref="System.ComponentModel.DescriptionAttribute"/> values on tool methods and their parameters.
+/// These descriptions are surfaced to AI models and help them determine when and how to use the tool, what values to pass for each parameter,
+/// and what constraints the parameters have. Well-written descriptions reduce incorrect tool invocations and improve the quality of
+/// model interactions.
+/// </para>
+/// <para>
 /// Return values from a method are used to create the <see cref="CallToolResult"/> that is sent back to the client:
 /// </para>
 /// <list type="table">

src/ModelContextProtocol.Core/Server/McpServerToolAttribute.cs

@@ -82,6 +82,26 @@ namespace ModelContextProtocol.Server;
 /// to provide data to the method.
 /// </para>
 /// <para>
+/// The tool method is responsible for validating its own input arguments (e.g., checking required fields, value ranges, string lengths, or
+/// any other business rules). Data annotations such as <c>RequiredAttribute</c> and
+/// <c>MaxLengthAttribute</c> on parameter types influence the generated JSON schema exposed
+/// to clients, but they are not enforced at runtime by the SDK. Validation should be performed explicitly within the tool method.
+/// </para>
+/// <para>
+/// To signal an error (including validation failures) back to the client, either throw an <see cref="McpException"/>
+/// or return a <see cref="CallToolResult"/> with <see cref="CallToolResult.IsError"/> set to <see langword="true"/>.
+/// When a tool throws an <see cref="McpException"/>, its <see cref="Exception.Message"/> is included in the error result
+/// sent to the client. Throwing any other exception type also results in an error <see cref="CallToolResult"/>, but with
+/// a generic error message (to avoid leaking sensitive information). Alternatively, a tool can declare a return type of
+/// <see cref="CallToolResult"/> to have full control over both success and error responses.
+/// </para>
+/// <para>
+/// It is important to provide clear <see cref="System.ComponentModel.DescriptionAttribute"/> values on tool methods and their parameters.
+/// These descriptions are surfaced to AI models and help them determine when and how to use the tool, what values to pass for each parameter,
+/// and what constraints the parameters have. Well-written descriptions reduce incorrect tool invocations and improve the quality of
+/// model interactions.
+/// </para>
+/// <para>
 /// Return values from a method are used to create the <see cref="CallToolResult"/> that is sent back to the client:
 /// </para>
 /// <list type="table">