Replace CallToolResult<T> with OutputSchemaType on McpServerToolAttribute

Remove CallToolResult<T> and ICallToolResultTyped - they conflated the success
type with the error type, making it impossible to provide meaningful error
messages when IsError is true and T is not string.

Add OutputSchemaType (Type?) property to McpServerToolAttribute, which
decouples the output schema type from the return type. Methods can return T
directly (throw for errors) or CallToolResult for full control over error
messages, while OutputSchemaType independently specifies the schema.

Also update CallToolAsync<T> to concatenate all TextContentBlock texts
(with newline separator) for error messages instead of using only the first.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: stephentoub

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

@@ -950,8 +950,10 @@ public ValueTask<CallToolResult> CallToolAsync(
 
         if (result.IsError is true)
         {
-            string errorMessage = result.Content.OfType<TextContentBlock>().FirstOrDefault()?.Text ?? "Tool call failed.";
-            throw new McpException(errorMessage);
+            string errorMessage = string.Join(
+                "\n",
+                result.Content.OfType<TextContentBlock>().Select(c => c.Text));
+            throw new McpException(errorMessage.Length > 0 ? errorMessage : "Tool call failed.");
         }
 
         var serializerOptions = options?.JsonSerializerOptions ?? McpJsonUtilities.DefaultOptions;

src/ModelContextProtocol.Core/Protocol/CallToolResultOfT.cs

@@ -174,6 +174,7 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
     {
         McpServerToolCreateOptions newOptions = options?.Clone() ?? new();
 
+        Type? outputSchemaType = null;
         if (method.GetCustomAttribute<McpServerToolAttribute>() is { } toolAttr)
         {
             newOptions.Name ??= toolAttr.Name;
@@ -214,6 +215,8 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
             {
                 newOptions.UseStructuredContent = true;
             }
+
+            outputSchemaType = toolAttr.OutputSchemaType;
         }
 
         if (method.GetCustomAttribute<DescriptionAttribute>() is { } descAttr)
@@ -224,10 +227,8 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
         // Set metadata if not already provided
         newOptions.Metadata ??= CreateMetadata(method);
 
-        // Generate the output schema from the return type if needed.
-        // UseStructuredContent on the attribute or options 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);
+        // Generate the output schema from the specified type or the return type.
+        // Priority: OutputSchemaType (explicit) > UseStructuredContent (infer from return type).
         if (outputSchemaType is null && newOptions.UseStructuredContent)
         {
             outputSchemaType = method.ReturnType;
@@ -323,8 +324,6 @@ public override async ValueTask<CallToolResult> InvokeAsync(
 
             CallToolResult callToolResponse => callToolResponse,
 
-            ICallToolResultTyped typed => typed.ToCallToolResult(AIFunction.JsonSerializerOptions),
-
             _ => new()
             {
                 Content = [new TextContentBlock { Text = JsonSerializer.Serialize(result, AIFunction.JsonSerializerOptions.GetTypeInfo(typeof(object))) }],
@@ -381,28 +380,6 @@ private static bool IsAsyncMethod(MethodInfo method)
         return false;
     }
 
-    /// <summary>
-    /// If the specified 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(Type returnType)
-    {
-        if (returnType.IsGenericType)
-        {
-            Type genericDef = returnType.GetGenericTypeDefinition();
-            if (genericDef == typeof(Task<>) || genericDef == typeof(ValueTask<>))
-            {
-                returnType = returnType.GetGenericArguments()[0];
-            }
-        }
-
-        if (returnType.IsGenericType && returnType.GetGenericTypeDefinition() == typeof(CallToolResult<>))
-        {
-            return returnType.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/AIFunctionMcpServerTool.cs

@@ -142,17 +142,10 @@ 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="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>
-///   <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>
+///     <description>Serialized to JSON and returned as a single <see cref="ContentBlock"/> object with <see cref="ContentBlock.Type"/> set to "text".
+///     When <see cref="McpServerToolAttribute.UseStructuredContent"/> is enabled, the serialized value is also set as <see cref="CallToolResult.StructuredContent"/>
+///     and used to generate the <see cref="Tool.OutputSchema"/>.</description>
 ///   </item>
 /// </list>
 /// </remarks>

src/ModelContextProtocol.Core/Server/McpServerTool.cs

@@ -138,17 +138,10 @@ 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="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>
-///   <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>
+///     <description>Serialized to JSON and returned as a single <see cref="ContentBlock"/> object with <see cref="ContentBlock.Type"/> set to "text".
+///     When <see cref="UseStructuredContent"/> is enabled, the serialized value is also set as <see cref="CallToolResult.StructuredContent"/>
+///     and used to generate the <see cref="Tool.OutputSchema"/>.</description>
 ///   </item>
 /// </list>
 /// </remarks>
@@ -269,11 +262,42 @@ 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"/> 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 <see cref="Tool.OutputSchema"/>.
+    /// </summary>
+    /// <value>
+    /// The default is <see langword="null"/>.
+    /// </value>
+    /// <remarks>
+    /// <para>
+    /// When set, the specified type is used to generate a JSON Schema that is advertised as the tool's
+    /// <see cref="Tool.OutputSchema"/>. 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 automatically enables structured content behavior, equivalent to
+    /// setting <see cref="UseStructuredContent"/> to <see langword="true"/>.
+    /// </para>
+    /// <para>
+    /// For Native AOT scenarios, use <see cref="McpServerToolCreateOptions.OutputSchema"/> to provide
+    /// a pre-generated JSON Schema instead.
+    /// </para>
+    /// </remarks>
+    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicProperties)]
+    public Type? OutputSchemaType { get; set; }
+
     /// <summary>
     /// Gets or sets the source URI for the tool's icon.
     /// </summary>