Add McpClientTool.WithResultMarshaling to let hosts control InvokeAsync results

McpClientTool.InvokeCoreAsync applies a fixed marshaling policy: content
blocks become AIContent when the result carries nothing else, and otherwise
the entire CallToolResult is serialized to a JsonElement. Because the
returned value is what IChatClient pipelines surface to the AI model, that
policy makes consequential decisions on the host's behalf: any application
_meta key (e.g. a correlation id intended for the host) flips a plain text
result into a JSON envelope handed to the model with the _meta included;
isError results reach the model as textual JSON rather than the provider's
native error signaling; and results carrying both content and
structuredContent are forwarded in duplicate. Hosts currently have no way
to opt out short of abandoning McpClientTool for a hand-rolled AIFunction.

Add WithResultMarshaling(Func<CallToolResult, CancellationToken,
ValueTask<object?>>), following the existing With* clone pattern. When
supplied, the delegate receives the raw CallToolResult and fully replaces
the built-in conversion, giving hosts exact control over what is surfaced
to consumers. It plays the same role for tool results that
AIFunctionFactoryOptions.MarshalResult plays for factory-created functions.
Default behavior is unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: PederHP

src/ModelContextProtocol.Core/Client/McpClientTool.cs

@@ -30,6 +30,7 @@ public sealed class McpClientTool : AIFunction
     private readonly string _description;
     private readonly IProgress<ProgressNotificationValue>? _progress;
     private readonly JsonObject? _meta;
+    private readonly Func<CallToolResult, CancellationToken, ValueTask<object?>>? _marshalResult;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="McpClientTool"/> class.
@@ -68,6 +69,7 @@ public McpClientTool(
         _description = tool.Description ?? string.Empty;
         _progress = null;
         _meta = null;
+        _marshalResult = null;
     }
 
     internal McpClientTool(
@@ -77,7 +79,8 @@ internal McpClientTool(
         string? name = null,
         string? description = null,
         IProgress<ProgressNotificationValue>? progress = null,
-        JsonObject? meta = null)
+        JsonObject? meta = null,
+        Func<CallToolResult, CancellationToken, ValueTask<object?>>? marshalResult = null)
     {
         _client = client;
         ProtocolTool = tool;
@@ -86,6 +89,7 @@ internal McpClientTool(
         _description = description ?? tool.Description ?? string.Empty;
         _progress = progress;
         _meta = meta;
+        _marshalResult = marshalResult;
     }
 
     /// <summary>
@@ -128,6 +132,13 @@ internal McpClientTool(
         };
         CallToolResult result = await CallAsync(arguments, _progress, options, cancellationToken).ConfigureAwait(false);
 
+        // If the host supplied its own result marshaler, it fully controls how the CallToolResult is
+        // surfaced to consumers; the default translation below is bypassed entirely.
+        if (_marshalResult is not null)
+        {
+            return await _marshalResult(result, cancellationToken).ConfigureAwait(false);
+        }
+
         // We want to translate the result content into AIContent, using AIContent as the exchange types, so
         // that downstream IChatClients can specialize handling based on the content (e.g. sending image content
         // back to the AI service as a multi-modal tool response). However, when there is additional information
@@ -268,7 +279,7 @@ public ValueTask<CallToolResult> CallAsync(
     /// </para>
     /// </remarks>
     public McpClientTool WithName(string name) =>
-        new(_client, ProtocolTool, JsonSerializerOptions, name, _description, _progress, _meta);
+        new(_client, ProtocolTool, JsonSerializerOptions, name, _description, _progress, _meta, _marshalResult);
 
     /// <summary>
     /// Creates a new instance of the tool but modified to return the specified description from its <see cref="Description"/> property.
@@ -292,7 +303,7 @@ public McpClientTool WithName(string name) =>
     /// </remarks>
     /// <returns>A new instance of <see cref="McpClientTool"/> with the provided description.</returns>
     public McpClientTool WithDescription(string description) =>
-        new(_client, ProtocolTool, JsonSerializerOptions, _name, description, _progress, _meta);
+        new(_client, ProtocolTool, JsonSerializerOptions, _name, description, _progress, _meta, _marshalResult);
 
     /// <summary>
     /// Creates a new instance of the tool but modified to report progress via the specified <see cref="IProgress{T}"/>.
@@ -316,7 +327,7 @@ public McpClientTool WithProgress(IProgress<ProgressNotificationValue> progress)
     {
         Throw.IfNull(progress);
 
-        return new McpClientTool(_client, ProtocolTool, JsonSerializerOptions, _name, _description, progress, _meta);
+        return new McpClientTool(_client, ProtocolTool, JsonSerializerOptions, _name, _description, progress, _meta, _marshalResult);
     }
 
     /// <summary>
@@ -346,5 +357,45 @@ public McpClientTool WithProgress(IProgress<ProgressNotificationValue> progress)
     /// </remarks>
     /// <returns>A new instance of <see cref="McpClientTool"/>, configured with the provided metadata.</returns>
     public McpClientTool WithMeta(JsonObject? meta) =>
-        new McpClientTool(_client, ProtocolTool, JsonSerializerOptions, _name, _description, _progress, meta);
+        new McpClientTool(_client, ProtocolTool, JsonSerializerOptions, _name, _description, _progress, meta, _marshalResult);
+
+    /// <summary>
+    /// Creates a new instance of the tool but modified to use the specified delegate to produce the value
+    /// returned from <see cref="AIFunction.InvokeAsync"/>, replacing the default marshaling.
+    /// </summary>
+    /// <param name="marshalResult">
+    /// The delegate invoked with the <see cref="CallToolResult"/> produced by the tool call. Whatever it
+    /// returns becomes the return value of <see cref="AIFunction.InvokeAsync"/>.
+    /// </param>
+    /// <remarks>
+    /// <para>
+    /// By default, <see cref="AIFunction.InvokeAsync"/> applies a built-in marshaling policy: content blocks are
+    /// converted to <see cref="AIContent"/> when the result carries no additional information, and otherwise the
+    /// entire <see cref="CallToolResult"/> is serialized to a <see cref="JsonElement"/> — including
+    /// <see cref="CallToolResult.StructuredContent"/>, <see cref="CallToolResult.IsError"/>, and any
+    /// <c>_meta</c>. When these tools are used with clients such as <c>IChatClient</c>, the returned value is
+    /// what gets surfaced to the AI model, so hosts may need precise control over that shape: keeping
+    /// host-only metadata out of model context, choosing between <see cref="CallToolResult.Content"/> and
+    /// <see cref="CallToolResult.StructuredContent"/>, or applying their own error handling for
+    /// <see cref="CallToolResult.IsError"/> results.
+    /// </para>
+    /// <para>
+    /// The delegate assumes full responsibility for the returned value; none of the default conversion runs.
+    /// Only one delegate can be specified at a time. Calling <see cref="WithResultMarshaling"/> again
+    /// replaces any previously specified delegate.
+    /// </para>
+    /// <para>
+    /// This serves the same role for tool results that
+    /// <c>Microsoft.Extensions.AI.AIFunctionFactoryOptions.MarshalResult</c> serves for factory-created
+    /// functions.
+    /// </para>
+    /// </remarks>
+    /// <returns>A new instance of <see cref="McpClientTool"/>, configured with the provided delegate.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="marshalResult"/> is <see langword="null"/>.</exception>
+    public McpClientTool WithResultMarshaling(Func<CallToolResult, CancellationToken, ValueTask<object?>> marshalResult)
+    {
+        Throw.IfNull(marshalResult);
+
+        return new McpClientTool(_client, ProtocolTool, JsonSerializerOptions, _name, _description, _progress, _meta, marshalResult);
+    }
 }

tests/ModelContextProtocol.Tests/Client/McpClientToolTests.cs

@@ -476,6 +476,80 @@ public async Task ErrorWithMetaTool_ReturnsJsonElement()
         Assert.Equal(JsonValueKind.Array, content.ValueKind);
     }
 
+    [Fact]
+    public async Task WithResultMarshaling_ReceivesRawCallToolResult_AndControlsReturnValue()
+    {
+        await using McpClient client = await CreateMcpClientForServer();
+        var tools = await client.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        CallToolResult? observed = null;
+        var tool = tools.Single(t => t.Name == "meta_tool").WithResultMarshaling((result, cancellationToken) =>
+        {
+            observed = result;
+            return new ValueTask<object?>("marshaled");
+        });
+
+        var result = await tool.InvokeAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("marshaled", result);
+        Assert.NotNull(observed);
+        Assert.Equal("customValue", observed.Meta?["customKey"]?.GetValue<string>());
+        Assert.Equal("Content with meta", Assert.IsType<TextContentBlock>(observed.Content[0]).Text);
+    }
+
+    [Fact]
+    public async Task WithResultMarshaling_CanKeepMetaOutOfReturnedValue()
+    {
+        await using McpClient client = await CreateMcpClientForServer();
+        var tools = await client.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        // The default marshaling would return the whole CallToolResult as a JsonElement, _meta included.
+        // A host-supplied marshaler can surface only the content blocks.
+        var tool = tools.Single(t => t.Name == "meta_tool").WithResultMarshaling((result, cancellationToken) =>
+            new ValueTask<object?>(result.Content.Select(c => c.ToAIContent()).ToArray()));
+
+        var result = await tool.InvokeAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        var aiContents = Assert.IsType<AIContent[]>(result);
+        var textContent = Assert.IsType<TextContent>(Assert.Single(aiContents));
+        Assert.Equal("Content with meta", textContent.Text);
+    }
+
+    [Fact]
+    public async Task WithResultMarshaling_ReplacesDefaultConversionForSimpleContent()
+    {
+        await using McpClient client = await CreateMcpClientForServer();
+        var tools = await client.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        // Without the marshaler this would return a single TextContent; with it, the host gets the
+        // typed CallToolResult itself.
+        var tool = tools.Single(t => t.Name == "text_only_tool").WithResultMarshaling((result, cancellationToken) =>
+            new ValueTask<object?>(result));
+
+        var result = await tool.InvokeAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        var callToolResult = Assert.IsType<CallToolResult>(result);
+        Assert.Equal("Simple text result", Assert.IsType<TextContentBlock>(callToolResult.Content[0]).Text);
+    }
+
+    [Fact]
+    public async Task WithResultMarshaling_IsPreservedByOtherWithMethods()
+    {
+        await using McpClient client = await CreateMcpClientForServer();
+        var tools = await client.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        var tool = tools.Single(t => t.Name == "text_only_tool")
+            .WithResultMarshaling((result, cancellationToken) => new ValueTask<object?>("marshaled"))
+            .WithName("renamed_tool")
+            .WithDescription("renamed description");
+
+        Assert.Equal("renamed_tool", tool.Name);
+
+        var result = await tool.InvokeAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("marshaled", result);
+    }
+
     [Fact]
     public async Task BinaryResourceTool_ReturnsSingleDataContent()
     {