PR feedback: differentiate between reflection and SG

Author: MackinnonBuck

docs/experimental.md

@@ -37,11 +37,16 @@ For a full list of experimental diagnostic IDs and their descriptions, see the [
 
 Experimental properties on protocol types are fully serialized and deserialized when using the SDK's built-in serialization via <xref:ModelContextProtocol.McpJsonUtilities.DefaultOptions>. This means experimental data is transmitted on the wire even if your application code doesn't directly interact with it, preserving protocol compatibility.
 
-### Custom `JsonSerializerContext`
+The behavior of experimental properties differs depending on whether you use [reflection-based or source-generated](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/source-generation) serialization:
+
+- **Reflection-based serialization** (the default when no `JsonSerializerContext` is used): Experimental properties are included. No special configuration is needed.
+- **Source-generated serialization** (using a custom `JsonSerializerContext`): Experimental properties are **not** included in your context's serialization contract. This is by design, as it protects your compiled code against binary breaking changes to experimental APIs.
 
-If you define your own `JsonSerializerContext` that includes MCP protocol types, experimental properties will not be included in your context's serialization contract. This is by design, as it protects your compiled code against binary breaking changes to experimental APIs.
+This means that switching between reflection-based and source-generated serialization can silently change which properties are serialized. To avoid this, source-generation users should configure a `TypeInfoResolverChain` as described below.
+
+### Custom `JsonSerializerContext`
 
-To ensure consistent serialization behavior that always includes experimental properties, configure a `TypeInfoResolverChain` so the SDK's resolver handles MCP types:
+If you define your own `JsonSerializerContext` that includes MCP protocol types, configure a `TypeInfoResolverChain` so the SDK's resolver handles MCP types:
 
 ```csharp
 using ModelContextProtocol;