Merge branch 'main' into copilot/normalize-calltoolresult-content

Author: stephentoub

Directory.Packages.props

@@ -92,6 +92,6 @@
     <PackageVersion Include="xunit.v3" Version="3.2.2" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
     <PackageVersion Include="System.Net.Http" Version="4.3.4" />
-    <PackageVersion Include="JsonSchema.Net" Version="9.1.0" />
+    <PackageVersion Include="JsonSchema.Net" Version="9.1.1" />
   </ItemGroup>
 </Project>

src/ModelContextProtocol.Core/Protocol/ToolAnnotations.cs

@@ -33,11 +33,11 @@ public sealed class ToolAnnotations
     /// Gets or sets a value that indicates whether the tool can perform destructive updates to its environment.
     /// </summary>
     /// <value>
-    /// The default is <see langword="true"/>.
+    /// <see langword="true"/> if the tool can perform destructive updates to its environment;
+    /// <see langword="false"/> if the tool performs only additive updates;
+    /// <see langword="null"/> if unspecified, in which case clients should assume <see langword="true"/>.
     /// </value>
     /// <remarks>
-    /// If <see langword="true"/>, the tool can perform destructive updates to its environment.
-    /// If <see langword="false"/>, the tool performs only additive updates.
     /// This property is most relevant when the tool modifies its environment (ReadOnly = false).
     /// </remarks>
     [JsonPropertyName("destructiveHint")]
@@ -49,8 +49,8 @@ public sealed class ToolAnnotations
     /// </summary>
     /// <value>
     /// <see langword="true"/> if calling the tool repeatedly with the same arguments
-    /// has no additional effect on the environment; <see langword="false"/> if it does.
-    /// The default is <see langword="false"/>.
+    /// has no additional effect on the environment; <see langword="false"/> if it does;
+    /// <see langword="null"/> if unspecified, in which case clients should assume <see langword="false"/>.
     /// </value>
     /// <remarks>
     /// This property is most relevant when the tool modifies its environment (ReadOnly = false).
@@ -62,9 +62,9 @@ public sealed class ToolAnnotations
     /// Gets or sets a value that indicates whether this tool can interact with an "open world" of external entities.
     /// </summary>
     /// <value>
-    /// <see langword="true"/> if the tool can interact with an unpredictable or dynamic set of entities (like web search).
-    /// <see langword="false"/> if the tool's domain of interaction is closed and well-defined (like memory access).
-    /// The default is <see langword="true"/>.
+    /// <see langword="true"/> if the tool can interact with an unpredictable or dynamic set of entities (like web search);
+    /// <see langword="false"/> if the tool's domain of interaction is closed and well-defined (like memory access);
+    /// <see langword="null"/> if unspecified, in which case clients should assume <see langword="true"/>.
     /// </value>
     [JsonPropertyName("openWorldHint")]
     public bool? OpenWorldHint { get; set; }
@@ -73,9 +73,9 @@ public sealed class ToolAnnotations
     /// Gets or sets a value that indicates whether this tool modifies its environment.
     /// </summary>
     /// <value>
-    /// <see langword="true"/> if the tool only performs read operations without changing state.
-    /// <see langword="false"/> if the tool can make modifications to its environment.
-    /// The default is <see langword="false"/>.
+    /// <see langword="true"/> if the tool only performs read operations without changing state;
+    /// <see langword="false"/> if the tool can make modifications to its environment;
+    /// <see langword="null"/> if unspecified, in which case clients should assume <see langword="false"/>.
     /// </value>
     /// <remarks>
     /// <para>

src/ModelContextProtocol.Core/Server/McpServerPrimitiveCollection.cs

@@ -120,7 +120,7 @@ public virtual bool TryGetPrimitive(string name, [NotNullWhen(true)] out T? prim
 
     /// <summary>Checks if a specific primitive is present in the collection of primitives.</summary>
     /// <param name="primitive">The primitive to search for in the collection.</param>
-    /// <see langword="true"/> if the primitive was found in the collection and returned; <see langword="false"/> if it wasn't found.
+    /// <returns><see langword="true"/> if the primitive was found in the collection and returned; <see langword="false"/> if it wasn't found.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="primitive"/> is <see langword="null"/>.</exception>
     public virtual bool Contains(T primitive)
     {