Add CallToolResult<T> and CallToolAsync<T>, remove OutputSchemaType from attribute

- Remove OutputSchemaType from McpServerToolAttribute (keep OutputSchema on options)
- Add sealed CallToolResult<T> class as a peer of CallToolResult with T Content
- Add ICallToolResultTyped internal interface for generic pattern matching
- Update AIFunctionMcpServerTool to recognize CallToolResult<T> return type:
  - DeriveOptions detects CallToolResult<T> and generates OutputSchema from T
  - InvokeAsync handles ICallToolResultTyped to convert to CallToolResult
- Add CallToolAsync<T> to McpClient that deserializes StructuredContent/Content as T
- Update XML doc comments on McpServerTool and McpServerToolAttribute

Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>

Author: Copilot

src/ModelContextProtocol.Core/Client/McpClient.Methods.cs

@@ -4,6 +4,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json;
 using System.Text.Json.Nodes;
+using System.Text.Json.Serialization.Metadata;
 
 namespace ModelContextProtocol.Client;
 
@@ -913,6 +914,67 @@ public ValueTask<CallToolResult> CallToolAsync(
             cancellationToken: cancellationToken);
     }
 
+    /// <summary>
+    /// Invokes a tool on the server and deserializes the result as a strongly-typed <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type to deserialize the tool's structured content or text content into.</typeparam>
+    /// <param name="toolName">The name of the tool to call on the server.</param>
+    /// <param name="arguments">An optional dictionary of arguments to pass to the tool.</param>
+    /// <param name="progress">An optional progress reporter for server notifications.</param>
+    /// <param name="options">Optional request options including metadata, serialization settings, and progress tracking.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The deserialized result from the tool execution.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="toolName"/> is <see langword="null"/>.</exception>
+    /// <exception cref="McpException">
+    /// The request failed, the server returned an error response, or <see cref="CallToolResult.IsError"/> was <see langword="true"/>.
+    /// </exception>
+    /// <exception cref="JsonException">The result content could not be deserialized as <typeparamref name="T"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// This method calls the existing <see cref="CallToolAsync(string, IReadOnlyDictionary{string, object?}?, IProgress{ProgressNotificationValue}?, RequestOptions?, CancellationToken)"/>
+    /// and then deserializes the result. If the result has <see cref="CallToolResult.StructuredContent"/>, that is deserialized
+    /// as <typeparamref name="T"/>. Otherwise, if the result has text content, the text of the first <see cref="TextContentBlock"/>
+    /// is deserialized as <typeparamref name="T"/>.
+    /// </para>
+    /// <para>
+    /// If <see cref="CallToolResult.IsError"/> is <see langword="true"/>, an <see cref="McpException"/> is thrown
+    /// with the error content details.
+    /// </para>
+    /// </remarks>
+    public async ValueTask<T> CallToolAsync<T>(
+        string toolName,
+        IReadOnlyDictionary<string, object?>? arguments = null,
+        IProgress<ProgressNotificationValue>? progress = null,
+        RequestOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        CallToolResult result = await CallToolAsync(toolName, arguments, progress, options, cancellationToken).ConfigureAwait(false);
+
+        if (result.IsError is true)
+        {
+            string errorMessage = result.Content.Count > 0 && result.Content[0] is TextContentBlock textBlock
+                ? textBlock.Text
+                : "The tool call returned an error.";
+            throw new McpException(errorMessage);
+        }
+
+        var serializerOptions = options?.JsonSerializerOptions ?? McpJsonUtilities.DefaultOptions;
+        JsonTypeInfo<T> typeInfo = (JsonTypeInfo<T>)serializerOptions.GetTypeInfo(typeof(T));
+
+        // Prefer StructuredContent if available, otherwise fall back to text content
+        if (result.StructuredContent is { } structuredContent)
+        {
+            return JsonSerializer.Deserialize(structuredContent, typeInfo)!;
+        }
+
+        if (result.Content.Count > 0 && result.Content[0] is TextContentBlock textContent)
+        {
+            return JsonSerializer.Deserialize(textContent.Text, typeInfo)!;
+        }
+
+        throw new McpException("The tool call did not return any content that could be deserialized.");
+    }
+
     /// <summary>
     /// Invokes a tool on the server as a task for long-running operations.
     /// </summary>

src/ModelContextProtocol.Core/Protocol/CallToolResultOfT.cs

@@ -0,0 +1,87 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents a strongly-typed result of a <see cref="RequestMethods.ToolsCall"/> request.
+/// </summary>
+/// <typeparam name="T">
+/// The type of the structured content returned by the tool. This type is used to infer the
+/// <see cref="Tool.OutputSchema"/> advertised by the tool.
+/// </typeparam>
+/// <remarks>
+/// <para>
+/// <see cref="CallToolResult{T}"/> provides a way to return strongly-typed structured content from a tool
+/// while still providing access to <see cref="Result.Meta"/> and <see cref="IsError"/>. When a tool method
+/// returns <see cref="CallToolResult{T}"/>, the SDK uses <typeparamref name="T"/> to infer the output schema
+/// and serializes <see cref="Content"/> as both the text content and structured content of the response.
+/// </para>
+/// <para>
+/// This type is a peer of <see cref="CallToolResult"/>, not a subclass. Use <see cref="CallToolResult"/> when
+/// you need full control over individual content blocks, and <see cref="CallToolResult{T}"/> when you want
+/// the SDK to handle serialization of a strongly-typed result.
+/// </para>
+/// </remarks>
+public sealed class CallToolResult<T> : ICallToolResultTyped
+{
+    /// <summary>
+    /// Gets or sets the typed content returned by the tool.
+    /// </summary>
+    public T? Content { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value that indicates whether the tool call was unsuccessful.
+    /// </summary>
+    /// <value>
+    /// <see langword="true"/> to signify that the tool execution failed; <see langword="false"/> if it was successful.
+    /// </value>
+    /// <remarks>
+    /// <para>
+    /// Tool execution errors (including input validation errors, API failures, and business logic errors)
+    /// are reported with this property set to <see langword="true"/> and details in the <see cref="Content"/>
+    /// property, rather than as protocol-level errors.
+    /// </para>
+    /// <para>
+    /// This design allows language models to receive detailed error feedback and potentially self-correct
+    /// in subsequent requests.
+    /// </para>
+    /// </remarks>
+    public bool? IsError { get; set; }
+
+    /// <summary>
+    /// Gets or sets metadata reserved by MCP for protocol-level metadata.
+    /// </summary>
+    /// <remarks>
+    /// Implementations must not make assumptions about its contents.
+    /// </remarks>
+    public JsonObject? Meta { get; set; }
+
+    /// <inheritdoc/>
+    CallToolResult ICallToolResultTyped.ToCallToolResult(JsonSerializerOptions serializerOptions)
+    {
+        var typeInfo = serializerOptions.GetTypeInfo(typeof(T));
+
+        string json = JsonSerializer.Serialize(Content, typeInfo);
+        JsonNode? structuredContent = JsonSerializer.SerializeToNode(Content, typeInfo);
+
+        return new()
+        {
+            Content = [new TextContentBlock { Text = json }],
+            StructuredContent = structuredContent,
+            IsError = IsError,
+            Meta = Meta,
+        };
+    }
+}
+
+/// <summary>
+/// Internal interface for converting strongly-typed tool results to <see cref="CallToolResult"/>.
+/// </summary>
+internal interface ICallToolResultTyped
+{
+    /// <summary>
+    /// Converts the strongly-typed result to a <see cref="CallToolResult"/>.
+    /// </summary>
+    CallToolResult ToCallToolResult(JsonSerializerOptions serializerOptions);
+}

src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs

@@ -206,14 +206,6 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
 
             newOptions.UseStructuredContent = toolAttr.UseStructuredContent;
 
-            if (toolAttr.OutputSchemaType is { } outputSchemaType)
-            {
-                newOptions.UseStructuredContent = true;
-                newOptions.OutputSchema ??= AIJsonUtilities.CreateJsonSchema(outputSchemaType,
-                    serializerOptions: newOptions.SerializerOptions ?? McpJsonUtilities.DefaultOptions,
-                    inferenceOptions: newOptions.SchemaCreateOptions);
-            }
-
             if (toolAttr._taskSupport is { } taskSupport)
             {
                 newOptions.Execution ??= new ToolExecution();
@@ -235,6 +227,15 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
             newOptions.UseStructuredContent = true;
         }
 
+        // If the method returns CallToolResult<T>, automatically use T for the output schema
+        if (GetCallToolResultContentType(method) is { } contentType)
+        {
+            newOptions.UseStructuredContent = true;
+            newOptions.OutputSchema ??= AIJsonUtilities.CreateJsonSchema(contentType,
+                serializerOptions: newOptions.SerializerOptions ?? McpJsonUtilities.DefaultOptions,
+                inferenceOptions: newOptions.SchemaCreateOptions);
+        }
+
         return newOptions;
     }
 
@@ -319,6 +320,8 @@ public override async ValueTask<CallToolResult> InvokeAsync(
 
             CallToolResult callToolResponse => callToolResponse,
 
+            ICallToolResultTyped typedResult => typedResult.ToCallToolResult(AIFunction.JsonSerializerOptions),
+
             _ => new()
             {
                 Content = [new TextContentBlock { Text = JsonSerializer.Serialize(result, AIFunction.JsonSerializerOptions.GetTypeInfo(typeof(object))) }],
@@ -375,6 +378,33 @@ private static bool IsAsyncMethod(MethodInfo method)
         return false;
     }
 
+    /// <summary>
+    /// If the method's return type is <see cref="CallToolResult{T}"/> (possibly wrapped in <see cref="Task{TResult}"/>
+    /// or <see cref="ValueTask{TResult}"/>), returns the <c>T</c> type argument. Otherwise, returns <see langword="null"/>.
+    /// </summary>
+    private static Type? GetCallToolResultContentType(MethodInfo method)
+    {
+        Type t = method.ReturnType;
+
+        // Unwrap Task<T> or ValueTask<T>
+        if (t.IsGenericType)
+        {
+            Type genericDef = t.GetGenericTypeDefinition();
+            if (genericDef == typeof(Task<>) || genericDef == typeof(ValueTask<>))
+            {
+                t = t.GetGenericArguments()[0];
+            }
+        }
+
+        // Check if the unwrapped type is CallToolResult<T>
+        if (t.IsGenericType && t.GetGenericTypeDefinition() == typeof(CallToolResult<>))
+        {
+            return t.GetGenericArguments()[0];
+        }
+
+        return null;
+    }
+
     /// <summary>Creates metadata from attributes on the specified method and its declaring class, with the MethodInfo as the first item.</summary>
     internal static IReadOnlyList<object> CreateMetadata(MethodInfo method)
     {

src/ModelContextProtocol.Core/Server/McpServerTool.cs

@@ -122,6 +122,15 @@ namespace ModelContextProtocol.Server;
 ///     <description>Returned directly without modification.</description>
 ///   </item>
 ///   <item>
+///     <term><see cref="CallToolResult{T}"/></term>
+///     <description>
+///     The <c>T</c> content is serialized to JSON and used as both a <see cref="TextContentBlock"/>
+///     and as the <see cref="CallToolResult.StructuredContent"/>. The <see cref="CallToolResult{T}.IsError"/>
+///     and <see cref="CallToolResult{T}.Meta"/> properties are propagated to the resulting <see cref="CallToolResult"/>.
+///     The <c>T</c> type argument is also used to infer the <see cref="Tool.OutputSchema"/>.
+///     </description>
+///   </item>
+///   <item>
 ///     <term>Other types</term>
 ///     <description>Serialized to JSON and returned as a single <see cref="ContentBlock"/> object with <see cref="ContentBlock.Type"/> set to "text".</description>
 ///   </item>

src/ModelContextProtocol.Core/Server/McpServerToolAttribute.cs

@@ -118,6 +118,15 @@ namespace ModelContextProtocol.Server;
 ///     <description>Returned directly without modification.</description>
 ///   </item>
 ///   <item>
+///     <term><see cref="CallToolResult{T}"/></term>
+///     <description>
+///     The <c>T</c> content is serialized to JSON and used as both a <see cref="TextContentBlock"/>
+///     and as the <see cref="CallToolResult.StructuredContent"/>. The <see cref="CallToolResult{T}.IsError"/>
+///     and <see cref="CallToolResult{T}.Meta"/> properties are propagated to the resulting <see cref="CallToolResult"/>.
+///     The <c>T</c> type argument is also used to infer the <see cref="Tool.OutputSchema"/>.
+///     </description>
+///   </item>
+///   <item>
 ///     <term>Other types</term>
 ///     <description>Serialized to JSON and returned as a single <see cref="ContentBlock"/> object with <see cref="ContentBlock.Type"/> set to "text".</description>
 ///   </item>
@@ -240,33 +249,11 @@ public bool ReadOnly
     /// The default is <see langword="false"/>.
     /// </value>
     /// <remarks>
-    /// <para>
     /// When enabled, the tool will attempt to populate the <see cref="Tool.OutputSchema"/>
     /// and provide structured content in the <see cref="CallToolResult.StructuredContent"/> property.
-    /// </para>
-    /// <para>
-    /// Setting <see cref="OutputSchemaType"/> to a non-<see langword="null"/> value will automatically enable structured content.
-    /// </para>
     /// </remarks>
     public bool UseStructuredContent { get; set; }
 
-    /// <summary>
-    /// Gets or sets the type to use for generating the tool's output schema.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// When set, the SDK generates the <see cref="Tool.OutputSchema"/> from this type instead of
-    /// inferring it from the method's return type. This is particularly useful when the method
-    /// returns <see cref="CallToolResult"/> directly (for example, to control
-    /// <see cref="CallToolResult.IsError"/>), but the tool should still advertise a meaningful
-    /// output schema describing the shape of <see cref="CallToolResult.StructuredContent"/>.
-    /// </para>
-    /// <para>
-    /// Setting this property to a non-<see langword="null"/> value will automatically enable <see cref="UseStructuredContent"/>.
-    /// </para>
-    /// </remarks>
-    public Type? OutputSchemaType { get; set; }
-
     /// <summary>
     /// Gets or sets the source URI for the tool's icon.
     /// </summary>