Add CallToolResult<T>, CallToolAsync<T>, and OutputSchema for tools returning CallToolResult

[Copilot]

Tools returning CallToolResult directly (to control IsError, StructuredContent, etc.) had no way to advertise a meaningful output schema — the inferred schema would reflect CallToolResult itself rather than the actual structured content shape.

Changes

CallToolResult<T> (new type)

• Added sealed CallToolResult<T> that derives from Result (inheriting Meta) — a peer of CallToolResult where Content is T? instead of IList<ContentBlock>
• Also exposes bool? IsError for error signaling
• Implements internal ICallToolResultTyped interface with ToCallToolResult(JsonSerializerOptions) that serializes T once to JsonNode, then uses ToString() for the text content block

Server-side: AIFunctionMcpServerTool

• Recognizes CallToolResult<T> as a return type (including Task<CallToolResult<T>> and ValueTask<CallToolResult<T>>)
• Uses T to automatically infer the OutputSchema — consolidated into the existing schema detection code alongside task unwrapping and return-type inference
• During invocation, delegates to ICallToolResultTyped.ToCallToolResult() for serialization, propagating IsError and Meta
• XML doc comments on McpServerTool and McpServerToolAttribute updated to document CallToolResult<T> in the return type table

Client-side: CallToolAsync<T>

• Added CallToolAsync<T> on McpClient that calls the existing CallToolAsync, then deserializes the result as T?
• Deserializes StructuredContent (preferred) or the first TextContentBlock as T using OfType<TextContentBlock>().FirstOrDefault()
• Throws McpException if IsError is true — callers who need error details can use the non-generic CallToolAsync overload

McpServerToolCreateOptions.OutputSchema

• JsonElement? OutputSchema allows supplying a pre-built schema directly via options
• The presence of OutputSchema on the options determines whether structured output is used — UseStructuredContent was removed from McpServerToolCreateOptions
• UseStructuredContent remains on McpServerToolAttribute; when set, DeriveOptions generates the OutputSchema from the method's return type (using T from CallToolResult<T> if applicable)
• Explicit OutputSchema takes precedence over CallToolResult<T> inference

Precedence

McpServerToolCreateOptions.OutputSchema > CallToolResult<T> type inference > McpServerToolAttribute.UseStructuredContent return-type inference

Usage

// Via CallToolResult<T> — schema inferred from MyResponse
[McpServerTool]
public static CallToolResult<MyResponse> MyTool(string input)
{
    return new() { Content = new MyResponse { Name = "test", Score = 42 } };
}

// Via attribute — schema inferred from return type
[McpServerTool(UseStructuredContent = true)]
public static MyResponse MyTool(string input) { ... }

// Via options — supply schema directly
McpServerTool.Create(myDelegate, new McpServerToolCreateOptions
{
    OutputSchema = myJsonSchema,
});

// Client-side deserialization — returns T, throws on IsError
MyResponse? result = await client.CallToolAsync<MyResponse>("my_tool", args);

Testing

• 8 unit tests for CallToolResult<T> in McpServerToolTests (schema generation, serialization, IsError/Meta propagation, async methods, null content, explicit override)
• 6 integration tests in CallToolResultOfTTests (end-to-end client-server with CallToolAsync<T>, error handling, fallback to text content, schema advertisement, arguments)
• 3 existing OutputSchema via options tests retained

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Support specifying OutputSchema type independently of return type for tools returning CallToolResult</issue_title>
<issue_description>Is your feature request related to a problem? Please describe.
When a tool method returns CallToolResult directly (to control properties like Meta, IsError, or manually populate StructuredContent), the SDK cannot generate a meaningful OutputSchema for the tool. The output schema either reflects the shape of CallToolResult itself—which is an internal protocol type and useless to clients—or is omitted entirely.

This forces developers to choose between:

• Returning a strongly-typed object to get a proper OutputSchema, but losing control over Meta, IsError, and other CallToolResult properties.
• Returning CallToolResult for full response control, but with no way to advertise the actual shape of StructuredContent to clients.

Describe the solution you'd like
Allow developers to specify the output schema type independently of the return type, for example via an attribute parameter or a create option:

// Option A: Attribute-based
[McpServerTool(UseStructuredContent = true, OutputSchemaType = typeof(MyResponseType))]
public static CallToolResult my_tool(string input) { ... }



// Option B: Via McpServerToolCreateOptions
McpServerToolCreateOptions options = new()
{
    UseStructuredContent = true,
    OutputSchemaType = typeof(MyResponseType),
};

When OutputSchemaType is set, the SDK would generate the OutputSchema from that type while still allowing the method to return CallToolResult with full control over the response.

Describe alternatives you've considered

• Returning a typed object: Works for simple cases, but precludes setting Meta, IsError, or customizing Content independently of StructuredContent.
• Schema node transformation workaround: Creating a stub tool with McpServerTool.Create(() => new T()) solely to extract its output schema, then using SchemaCreateOptions.TransformSchemaNode on the real tool to replace the CallToolResult schema with the stub's. This works but is fragile, non-obvious, and requires significant boilerplate.
• Manually setting StructuredContent without UseStructuredContent: Provides structured data to clients but no OutputSchema is advertised in tools/list, so clients can't validate or understand the response shape ahead of time.

Additional context
This gap is particularly impactful in scenarios where tools need to return both structured content and out-of-band metadata via CallToolResult.Meta. 
</issue_description>

<agent_instructions>Add a Type? OutputSchemaType property to McpServerToolAttribute and a JsonElement? OutputSchema property to McpServerToolCreateOptions. The OutputSchema property, if it exists, will just be used to initialize the OutputSchema on the creation options using AIJsonUtilities. This let's someone using the attribute specify a type, and someone using the options bag directly either specify a type (with a call to AIJsonUtilities to create the schema) or just supply their own custom schema. If the schema is specified, UseStructuredOutput should be forced to true in the options bag. Make sure to add good test coverage of this in the existing test files. Also ensure any existing docs about UseStructuredOutput and [McpServerTool] are updated appropriately.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Support specifying OutputSchema type independently of return type for tools returning CallToolResult #1263

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[stephentoub]

@copilot

[mikekistler]

@copilot Please give a short explanation of the feature added in this PR from the perspective of a user of the SDK.

[Copilot]

@copilot Please give a short explanation of the feature added in this PR from the perspective of a user of the SDK.

This PR adds three main features:

1. CallToolResult<T> — a new return type for tool methods that gives you both structured content and control over IsError/Meta. The SDK infers the output schema from T:

[McpServerTool]
public static CallToolResult<MyResponse> MyTool(string input)
{
    return new() { Content = new MyResponse { Name = "test", Score = 42 } };
}

2. CallToolAsync<T> — a client-side method that calls a tool and deserializes the result as T:

MyResponse result = await client.CallToolAsync<MyResponse>("my_tool", args);

3. McpServerToolCreateOptions.OutputSchema — for advanced scenarios where you want to supply a custom JSON schema directly.

[stephentoub]

@copilot if IsError is true, are we now losing any message included in content?

[stephentoub]

Let's go back to it returning T. Then someone who wants the details can just use the non generic overload.

[Copilot]

Done in 24bbac3 — CallToolAsync<T> now returns T? and throws McpException with the error message text when IsError is true.

[stephentoub]

@copilot why can't all of this schema handling for CallToolResult be done where the rest of the schema detection is done? There's already code unwrapping tasks, creating return schema for the return type, etc. I'm missing why this needs to be done separately.

[Copilot]

Consolidated in 24bbac3 — unified into a single block after all attribute handling:

Type? outputSchemaType = GetCallToolResultContentType(method.ReturnType);
if (outputSchemaType is null && useStructuredContent)
{
    outputSchemaType = method.ReturnType;
}
if (outputSchemaType is not null)
{
    newOptions.OutputSchema ??= AIJsonUtilities.CreateJsonSchema(outputSchemaType, ...);
}

GetCallToolResultContentType always runs first (handles CallToolResult<T> with or without the attribute), then UseStructuredContent fills in the return type only when CallToolResult<T> wasn't detected.

[jeffhandley]

@copilot Provide bullets that capture breaking changes made in this PR. There can be 2 categories of breaking changes: API changes, and behavioral changes. These bullets will be included into upcoming release notes as described in docs/versioning.md.

[Copilot]

@copilot Provide bullets that capture breaking changes made in this PR. There can be 2 categories of breaking changes: API changes, and behavioral changes. These bullets will be included into upcoming...

API Breaking Changes

• McpServerToolCreateOptions.UseStructuredContent removed. The bool UseStructuredContent property was removed from McpServerToolCreateOptions. Structured content is now determined by the presence of OutputSchema on the options. The UseStructuredContent property remains on McpServerToolAttribute for attribute-based configuration. Code that was setting UseStructuredContent = true on the options should instead set OutputSchema to the desired JSON schema, or use CallToolResult<T> as the return type which automatically infers the schema.

Behavioral Breaking Changes

• UseStructuredContent on the attribute now generates the output schema in DeriveOptions rather than deferring to CreateOutputSchema. When McpServerToolAttribute.UseStructuredContent is true and the method returns CallToolResult<T>, the schema is now inferred from T instead of from the full CallToolResult<T> type. This fixes the schema to reflect the actual structured content type rather than the wrapper.

[mikekistler]

@stephentoub Do you think we should defer this until after v1.0, since now we think it will not create an breaking changes?

[stephentoub]

@stephentoub Do you think we should defer this until after v1.0, since now we think it will not create an breaking changes?

Yup, that was my suggestion offline. Thanks.