Address PR feedback on conceptual docs

- Add bulleted lists of all definition methods for tools, prompts, resources
  (attribute, Create factory, deriving, custom handler, request filter)
- Note DataContent from M.E.AI mapping to content blocks in tools and prompts
- Simplify roots example by removing unnecessary explicit capability config
- Add special parameter types note (McpServer, IProgress, ClaimsPrincipal, DI)
- Mention message filters for cancellation notification interception
- Use tool.CallAsync pattern in client tool consumption example
- Merge redundant intro in capabilities.md
- Simplify elicitation EnumSchemaOption syntax and remove auto-fill claim
- Simplify prompts intro text

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jeffhandley

docs/concepts/cancellation/cancellation.md

@@ -44,7 +44,7 @@ The cancellation notification includes:
 - **RequestId**: The ID of the request to cancel, allowing the receiver to correlate the cancellation with the correct in-flight request.
 - **Reason**: An optional human-readable reason for the cancellation.
 
-Cancellation notifications can be observed by registering a handler:
+Cancellation notifications can be observed by registering a handler. For broader interception of notifications and other messages, <xref:ModelContextProtocol.Server.McpMessageFilter> delegates can be added to the <xref:ModelContextProtocol.Server.McpMessageFilters.IncomingFilters> collection in <xref:ModelContextProtocol.Server.McpServerOptions.Filters>.
 
 ```csharp
 mcpClient.RegisterNotificationHandler(

docs/concepts/capabilities/capabilities.md

@@ -7,14 +7,10 @@ uid: capabilities
 
 ## Capabilities
 
-MCP uses a [capability negotiation] mechanism during connection initialization. Clients and servers exchange their supported capabilities, allowing each side to understand what features the other supports and adapt behavior accordingly.
+MCP uses a [capability negotiation] mechanism during connection setup. Clients and servers exchange their supported capabilities so each side can adapt its behavior accordingly. Both sides should check the other's capabilities before using optional features.
 
 [capability negotiation]: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
 
-### Overview
-
-During connection setup, clients and servers exchange their supported capabilities so each side can adapt its behavior accordingly. After initialization, both sides should check the other's capabilities before using optional features.
-
 ### Client capabilities
 
 <xref:ModelContextProtocol.Protocol.ClientCapabilities> declares what features the client supports:

docs/concepts/elicitation/elicitation.md

@@ -73,8 +73,6 @@ var result = await server.ElicitAsync(new ElicitRequestParams
 }, cancellationToken);
 ```
 
-If the client returns accepted content with missing fields, the server automatically fills those fields with their schema defaults. This ensures tools always receive complete data regardless of client behavior.
-
 #### Enum schema formats
 
 Enum schemas allow the server to present a set of choices to the user.
@@ -91,9 +89,9 @@ Enum schemas allow the server to present a set of choices to the user.
     Description = "Task priority",
     OneOf =
     [
-        new ElicitRequestParams.EnumSchemaOption { Const = "p0", Title = "Critical (P0)" },
-        new ElicitRequestParams.EnumSchemaOption { Const = "p1", Title = "High (P1)" },
-        new ElicitRequestParams.EnumSchemaOption { Const = "p2", Title = "Normal (P2)" },
+        new() { Const = "p0", Title = "Critical (P0)" },
+        new() { Const = "p1", Title = "High (P1)" },
+        new() { Const = "p2", Title = "Normal (P2)" },
     ],
     Default = "p2"
 },

docs/concepts/prompts/prompts.md

@@ -15,11 +15,19 @@ This document covers implementing prompts on the server, consuming them from the
 
 ### Defining prompts on the server
 
-Prompts are defined as methods marked with the <xref:ModelContextProtocol.Server.McpServerPromptAttribute> attribute within a class marked with <xref:ModelContextProtocol.Server.McpServerPromptTypeAttribute>. Prompts can return `ChatMessage` instances for simple text/image content, or <xref:ModelContextProtocol.Protocol.PromptMessage> instances when protocol-specific content types like <xref:ModelContextProtocol.Protocol.EmbeddedResourceBlock> are needed.
+Prompts can be defined in several ways:
+
+- Using the <xref:ModelContextProtocol.Server.McpServerPromptAttribute> attribute on methods within a class marked with <xref:ModelContextProtocol.Server.McpServerPromptTypeAttribute>
+- Using <xref:ModelContextProtocol.Server.McpServerPrompt.Create*> factory methods from a delegate, `MethodInfo`, or `AIFunction`
+- Deriving from <xref:ModelContextProtocol.Server.McpServerPrompt> or <xref:ModelContextProtocol.Server.DelegatingMcpServerPrompt>
+- Implementing a custom <xref:ModelContextProtocol.Server.McpRequestHandler`2> via <xref:ModelContextProtocol.Server.McpServerHandlers>
+- Implementing a low-level <xref:ModelContextProtocol.Server.McpRequestFilter`2>
+
+The attribute-based approach is the most common and is shown throughout this document. Prompts can return `ChatMessage` instances for simple text/image content, or <xref:ModelContextProtocol.Protocol.PromptMessage> instances when protocol-specific content types like <xref:ModelContextProtocol.Protocol.EmbeddedResourceBlock> are needed.
 
 #### Simple prompts
 
-A prompt without arguments returns a fixed message:
+A prompt without arguments:
 
 ```csharp
 [McpServerPromptType]
@@ -33,7 +41,7 @@ public class MyPrompts
 
 #### Prompts with arguments
 
-Prompts can accept parameters to customize the generated messages. Use `[Description]` attributes to document each parameter:
+Prompts can accept parameters to customize the generated messages. Use `[Description]` attributes to document each parameter. In addition to prompt arguments, methods can accept special parameter types that are resolved automatically: <xref:ModelContextProtocol.Server.McpServer>, `IProgress<ProgressNotificationValue>`, `ClaimsPrincipal`, and any service registered through dependency injection.
 
 ```csharp
 [McpServerPromptType]
@@ -66,7 +74,7 @@ builder.Services.AddMcpServer()
 
 ### Rich content in prompts
 
-Prompt messages can contain more than just text. For text and image content, use `ChatMessage` from Microsoft.Extensions.AI. For protocol-specific content types like embedded resources, use <xref:ModelContextProtocol.Protocol.PromptMessage> instead.
+Prompt messages can contain more than just text. For text and image content, use `ChatMessage` from Microsoft.Extensions.AI. `DataContent` is automatically mapped to the appropriate MCP content block: image MIME types become <xref:ModelContextProtocol.Protocol.ImageContentBlock>, audio MIME types become <xref:ModelContextProtocol.Protocol.AudioContentBlock>, and all other MIME types become <xref:ModelContextProtocol.Protocol.EmbeddedResourceBlock> with binary resource contents. For text embedded resources specifically, use <xref:ModelContextProtocol.Protocol.PromptMessage> directly.
 
 #### Image content
 

docs/concepts/resources/resources.md

@@ -15,7 +15,15 @@ This document covers implementing resources on the server, consuming them from t
 
 ### Defining resources on the server
 
-Resources are defined as methods marked with the <xref:ModelContextProtocol.Server.McpServerResourceAttribute> attribute within a class marked with <xref:ModelContextProtocol.Server.McpServerResourceTypeAttribute>. The attribute specifies the URI template that identifies the resource.
+Resources can be defined in several ways:
+
+- Using the <xref:ModelContextProtocol.Server.McpServerResourceAttribute> attribute on methods within a class marked with <xref:ModelContextProtocol.Server.McpServerResourceTypeAttribute>
+- Using <xref:ModelContextProtocol.Server.McpServerResource.Create*> factory methods from a delegate, `MethodInfo`, or `AIFunction`
+- Deriving from <xref:ModelContextProtocol.Server.McpServerResource> or <xref:ModelContextProtocol.Server.DelegatingMcpServerResource>
+- Implementing a custom <xref:ModelContextProtocol.Server.McpRequestHandler`2> via <xref:ModelContextProtocol.Server.McpServerHandlers>
+- Implementing a low-level <xref:ModelContextProtocol.Server.McpRequestFilter`2>
+
+The attribute-based approach is the most common and is shown throughout this document.
 
 #### Direct resources
 

docs/concepts/roots/roots.md

@@ -23,18 +23,11 @@ Each root is represented by a <xref:ModelContextProtocol.Protocol.Root> with a U
 
 ### Declaring roots capability on the client
 
-Clients advertise their support for roots in the capabilities sent during initialization. To enable roots, configure the <xref:ModelContextProtocol.Protocol.ClientCapabilities.Roots> property and provide a handler that returns the root list:
+Clients advertise their support for roots in the capabilities sent during initialization. The roots capability is created automatically when a roots handler is provided. Configure the handler through <xref:ModelContextProtocol.McpClientHandlers.RootsHandler>:
 
 ```csharp
 var options = new McpClientOptions
 {
-    Capabilities = new ClientCapabilities
-    {
-        Roots = new RootsCapability
-        {
-            ListChanged = true // Notify server when roots change
-        }
-    },
     Handlers = new McpClientHandlers
     {
         RootsHandler = (request, cancellationToken) =>

docs/concepts/tools/tools.md

@@ -15,7 +15,15 @@ This document covers tool content types, change notifications, and schema genera
 
 ### Defining tools on the server
 
-Tools are defined as methods marked with the <xref:ModelContextProtocol.Server.McpServerToolAttribute> attribute within a class marked with <xref:ModelContextProtocol.Server.McpServerToolTypeAttribute>. Parameters are automatically deserialized from JSON and documented using `[Description]` attributes.
+Tools can be defined in several ways:
+
+- Using the <xref:ModelContextProtocol.Server.McpServerToolAttribute> attribute on methods within a class marked with <xref:ModelContextProtocol.Server.McpServerToolTypeAttribute>
+- Using <xref:ModelContextProtocol.Server.McpServerTool.Create*> factory methods from a delegate, `MethodInfo`, or `AIFunction`
+- Deriving from <xref:ModelContextProtocol.Server.McpServerTool> or <xref:ModelContextProtocol.Server.DelegatingMcpServerTool>
+- Implementing a custom <xref:ModelContextProtocol.Server.McpRequestHandler`2> via <xref:ModelContextProtocol.Server.McpServerHandlers>
+- Implementing a low-level <xref:ModelContextProtocol.Server.McpRequestFilter`2>
+
+The attribute-based approach is the most common and is shown throughout this document. Parameters are automatically deserialized from JSON and documented using `[Description]` attributes. In addition to tool arguments, methods can accept special parameter types that are resolved automatically: <xref:ModelContextProtocol.Server.McpServer>, `IProgress<ProgressNotificationValue>`, `ClaimsPrincipal`, and any service registered through dependency injection.
 
 ```csharp
 [McpServerToolType]
@@ -37,7 +45,7 @@ builder.Services.AddMcpServer()
 
 ### Content types
 
-Tools can return various content types. The simplest is a `string`, which is automatically wrapped in a <xref:ModelContextProtocol.Protocol.TextContentBlock>. For richer content, tools can return one or more <xref:ModelContextProtocol.Protocol.ContentBlock> instances.
+Tools can return various content types. The simplest is a `string`, which is automatically wrapped in a <xref:ModelContextProtocol.Protocol.TextContentBlock>. For richer content, tools can return one or more <xref:ModelContextProtocol.Protocol.ContentBlock> instances. Tools can also return `DataContent` from Microsoft.Extensions.AI, which is automatically mapped to the appropriate MCP content block: image MIME types become <xref:ModelContextProtocol.Protocol.ImageContentBlock>, audio MIME types become <xref:ModelContextProtocol.Protocol.AudioContentBlock>, and all other MIME types become <xref:ModelContextProtocol.Protocol.EmbeddedResourceBlock> with binary resource contents.
 
 #### Text content
 
@@ -160,9 +168,9 @@ foreach (var tool in tools)
     Console.WriteLine($"{tool.Name}: {tool.Description}");
 }
 
-// Call a tool
-CallToolResult result = await client.CallToolAsync(
-    "echo",
+// Call a tool by finding it in the list
+McpClientTool echoTool = tools.First(t => t.Name == "echo");
+CallToolResult result = await echoTool.CallAsync(
     new Dictionary<string, object?> { ["message"] = "Hello!" });
 
 // Process the result content blocks
@@ -174,11 +182,9 @@ foreach (var content in result.Content)
             Console.WriteLine(text.Text);
             break;
         case ImageContentBlock image:
-            // image.DecodedData contains the raw bytes
             File.WriteAllBytes("output.png", image.DecodedData.ToArray());
             break;
         case AudioContentBlock audio:
-            // audio.DecodedData contains the raw bytes
             File.WriteAllBytes("output.wav", audio.DecodedData.ToArray());
             break;
         case EmbeddedResourceBlock resource:
@@ -195,7 +201,12 @@ Tool errors in MCP are distinct from protocol errors. When a tool encounters an
 
 #### Automatic exception handling
 
-When a tool method throws an exception, the server automatically catches it and returns a `CallToolResult` with `IsError = true`. <xref:ModelContextProtocol.McpProtocolException> is re-thrown as a JSON-RPC error, and `OperationCanceledException` is re-thrown when the cancellation token was triggered. All other exceptions are returned as tool error results. For <xref:ModelContextProtocol.McpException> subclasses, the exception message is included in the error text; for other exceptions, a generic message is returned to avoid leaking internal details.
+When a tool method throws an exception, the server catches it and returns a `CallToolResult` with `IsError = true`, with the following exceptions:
+
+- <xref:ModelContextProtocol.McpProtocolException> is re-thrown as a JSON-RPC error response (not a tool error result).
+- `OperationCanceledException` is re-thrown when the cancellation token was triggered.
+
+For all other exceptions, the error is returned as a tool result. If the exception derives from <xref:ModelContextProtocol.McpException> (excluding `McpProtocolException`, which is re-thrown above), its message is included in the error text; otherwise, a generic message is returned to avoid leaking internal details.
 
 ```csharp
 [McpServerTool, Description("Divides two numbers")]