CallToolResult<T> derives from Result, CallToolAsync<T> returns T and throws on IsError, consolidate schema handling

- CallToolResult<T> now derives from Result (inherits Meta), removed duplicate Meta property
- CallToolAsync<T> returns T? instead of CallToolResult<T>, throws McpException on IsError
- Consolidated schema handling in DeriveOptions: unified UseStructuredContent and
  CallToolResult<T> auto-detection into a single block
- Updated XML docs for cref changes (Result.Meta)

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

Author: Copilot

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

@@ -915,17 +915,17 @@ public ValueTask<CallToolResult> CallToolAsync(
     }
 
     /// <summary>
-    /// Invokes a tool on the server and deserializes the result as a strongly-typed <see cref="CallToolResult{T}"/>.
+    /// Invokes a tool on the server and deserializes the result as <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>A <see cref="CallToolResult{T}"/> containing the deserialized content, error state, and metadata.</returns>
+    /// <returns>The deserialized content of the tool result.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="toolName"/> is <see langword="null"/>.</exception>
-    /// <exception cref="McpException">The request failed or the server returned an error response.</exception>
+    /// <exception cref="McpException">The request failed, the server returned an error response, or <see cref="CallToolResult.IsError"/> is <see langword="true"/>.</exception>
     /// <exception cref="JsonException">The result content could not be deserialized as <typeparamref name="T"/>.</exception>
     /// <remarks>
     /// <para>
@@ -934,8 +934,12 @@ public ValueTask<CallToolResult> CallToolAsync(
     /// 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. To inspect
+    /// error details without an exception, use the non-generic <see cref="CallToolAsync(string, IReadOnlyDictionary{string, object?}?, IProgress{ProgressNotificationValue}?, RequestOptions?, CancellationToken)"/> overload instead.
+    /// </para>
     /// </remarks>
-    public async ValueTask<CallToolResult<T>> CallToolAsync<T>(
+    public async ValueTask<T?> CallToolAsync<T>(
         string toolName,
         IReadOnlyDictionary<string, object?>? arguments = null,
         IProgress<ProgressNotificationValue>? progress = null,
@@ -944,30 +948,27 @@ public async ValueTask<CallToolResult<T>> CallToolAsync<T>(
     {
         CallToolResult result = await CallToolAsync(toolName, arguments, progress, options, cancellationToken).ConfigureAwait(false);
 
-        T? content = default;
-
-        if (result.IsError is not true)
+        if (result.IsError is true)
         {
-            var serializerOptions = options?.JsonSerializerOptions ?? McpJsonUtilities.DefaultOptions;
-            JsonTypeInfo<T> typeInfo = (JsonTypeInfo<T>)serializerOptions.GetTypeInfo(typeof(T));
+            string errorMessage = result.Content.OfType<TextContentBlock>().FirstOrDefault()?.Text ?? "Tool call failed.";
+            throw new McpException(errorMessage);
+        }
 
-            // Prefer StructuredContent if available, otherwise fall back to text content
-            if (result.StructuredContent is { } structuredContent)
-            {
-                content = JsonSerializer.Deserialize(structuredContent, typeInfo);
-            }
-            else if (result.Content.OfType<TextContentBlock>().FirstOrDefault() is { } textContent)
-            {
-                content = JsonSerializer.Deserialize(textContent.Text, typeInfo);
-            }
+        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);
         }
 
-        return new()
+        if (result.Content.OfType<TextContentBlock>().FirstOrDefault() is { } textContent)
         {
-            Content = content,
-            IsError = result.IsError,
-            Meta = result.Meta,
-        };
+            return JsonSerializer.Deserialize(textContent.Text, typeInfo);
+        }
+
+        return default;
     }
 
     /// <summary>

src/ModelContextProtocol.Core/Protocol/CallToolResultOfT.cs

@@ -23,7 +23,7 @@ namespace ModelContextProtocol.Protocol;
 /// the SDK to handle serialization of a strongly-typed result.
 /// </para>
 /// </remarks>
-public sealed class CallToolResult<T> : ICallToolResultTyped
+public sealed class CallToolResult<T> : Result, ICallToolResultTyped
 {
     /// <summary>
     /// Gets or sets the typed content returned by the tool.
@@ -49,14 +49,6 @@ public sealed class CallToolResult<T> : ICallToolResultTyped
     /// </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)
     {

src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs

@@ -174,6 +174,7 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
     {
         McpServerToolCreateOptions newOptions = options?.Clone() ?? new();
 
+        bool useStructuredContent = false;
         if (method.GetCustomAttribute<McpServerToolAttribute>() is { } toolAttr)
         {
             newOptions.Name ??= toolAttr.Name;
@@ -210,15 +211,7 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
                 newOptions.Execution.TaskSupport ??= taskSupport;
             }
 
-            // When the attribute enables structured content, generate the output schema from the return type.
-            // If the return type is CallToolResult<T>, use T rather than the full return type.
-            if (toolAttr.UseStructuredContent)
-            {
-                Type outputType = GetCallToolResultContentType(method.ReturnType) ?? method.ReturnType;
-                newOptions.OutputSchema ??= AIJsonUtilities.CreateJsonSchema(outputType,
-                    serializerOptions: newOptions.SerializerOptions ?? McpJsonUtilities.DefaultOptions,
-                    inferenceOptions: newOptions.SchemaCreateOptions);
-            }
+            useStructuredContent = toolAttr.UseStructuredContent;
         }
 
         if (method.GetCustomAttribute<DescriptionAttribute>() is { } descAttr)
@@ -229,10 +222,18 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
         // Set metadata if not already provided
         newOptions.Metadata ??= CreateMetadata(method);
 
-        // If the method returns CallToolResult<T>, automatically use T for the output schema
-        if (GetCallToolResultContentType(method.ReturnType) is { } contentType)
+        // Generate the output schema from the return type if needed.
+        // UseStructuredContent on the attribute uses T from CallToolResult<T> or the return type directly.
+        // CallToolResult<T> return types automatically infer the schema from T even without UseStructuredContent.
+        Type? outputSchemaType = GetCallToolResultContentType(method.ReturnType);
+        if (outputSchemaType is null && useStructuredContent)
+        {
+            outputSchemaType = method.ReturnType;
+        }
+
+        if (outputSchemaType is not null)
         {
-            newOptions.OutputSchema ??= AIJsonUtilities.CreateJsonSchema(contentType,
+            newOptions.OutputSchema ??= AIJsonUtilities.CreateJsonSchema(outputSchemaType,
                 serializerOptions: newOptions.SerializerOptions ?? McpJsonUtilities.DefaultOptions,
                 inferenceOptions: newOptions.SchemaCreateOptions);
         }

src/ModelContextProtocol.Core/Server/McpServerTool.cs

@@ -146,7 +146,7 @@ namespace ModelContextProtocol.Server;
 ///     <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"/>.
+///     and <see cref="Result.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>

src/ModelContextProtocol.Core/Server/McpServerToolAttribute.cs

@@ -142,7 +142,7 @@ namespace ModelContextProtocol.Server;
 ///     <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"/>.
+///     and <see cref="Result.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>

tests/ModelContextProtocol.Tests/Server/CallToolResultOfTTests.cs

@@ -41,13 +41,13 @@ public async Task CallToolAsyncOfT_DeserializesStructuredContent()
             options: new() { JsonSerializerOptions = serOpts },
             cancellationToken: TestContext.Current.CancellationToken);
 
-        Assert.NotNull(result.Content);
-        Assert.Equal("Alice", result.Content.Name);
-        Assert.Equal(30, result.Content.Age);
+        Assert.NotNull(result);
+        Assert.Equal("Alice", result.Name);
+        Assert.Equal(30, result.Age);
     }
 
     [Fact]
-    public async Task CallToolAsyncOfT_PropagatesIsError()
+    public async Task CallToolAsyncOfT_ThrowsOnIsError()
     {
         JsonSerializerOptions serOpts = new() { TypeInfoResolver = new DefaultJsonTypeInfoResolver() };
         _toolCollection.Add(McpServerTool.Create(
@@ -57,12 +57,12 @@ public async Task CallToolAsyncOfT_PropagatesIsError()
         StartServer();
         var client = await CreateMcpClientForServer();
 
-        var result = await client.CallToolAsync<string>(
+        var ex = await Assert.ThrowsAsync<McpException>(() => client.CallToolAsync<string>(
             "error_tool",
             options: new() { JsonSerializerOptions = serOpts },
-            cancellationToken: TestContext.Current.CancellationToken);
+            cancellationToken: TestContext.Current.CancellationToken).AsTask());
 
-        Assert.True(result.IsError);
+        Assert.Contains("something went wrong", ex.Message);
     }
 
     [Fact]
@@ -82,9 +82,9 @@ public async Task CallToolAsyncOfT_FallsBackToTextContent()
             options: new() { JsonSerializerOptions = serOpts },
             cancellationToken: TestContext.Current.CancellationToken);
 
-        Assert.NotNull(result.Content);
-        Assert.Equal("Bob", result.Content.Name);
-        Assert.Equal(25, result.Content.Age);
+        Assert.NotNull(result);
+        Assert.Equal("Bob", result.Name);
+        Assert.Equal(25, result.Age);
     }
 
     [Fact]
@@ -128,9 +128,9 @@ public async Task CallToolAsyncOfT_WithAsyncTool_Works()
             options: new() { JsonSerializerOptions = serOpts },
             cancellationToken: TestContext.Current.CancellationToken);
 
-        Assert.NotNull(result.Content);
-        Assert.Equal("Charlie", result.Content.Name);
-        Assert.Equal(35, result.Content.Age);
+        Assert.NotNull(result);
+        Assert.Equal("Charlie", result.Name);
+        Assert.Equal(35, result.Age);
     }
 
     [Fact]
@@ -153,9 +153,9 @@ public async Task CallToolAsyncOfT_WithArguments_Works()
             options: new() { JsonSerializerOptions = serOpts },
             cancellationToken: TestContext.Current.CancellationToken);
 
-        Assert.NotNull(result.Content);
-        Assert.Equal("Diana", result.Content.Name);
-        Assert.Equal(28, result.Content.Age);
+        Assert.NotNull(result);
+        Assert.Equal("Diana", result.Name);
+        Assert.Equal(28, result.Age);
     }
 
     private class PersonData