Allow CallToolResult to be returned directly to support _meta field for OpenAI Apps

[BrandonShar]

This PR allows tools to directly return CallToolResult instead of having it cast automatically by the lowlevel server.

Motivation and Context

OpenAI's Apps SDK uses the _meta field of a tool call result to allow passing data to app components without them being seen by the model. This behavior is supported by the protocol, but isn't implemented in the SDK.

In order to maximize discoverability and future change-abililty, I added the ability to directly return the CallToolResult, which already supports the _meta field, rather than add additional tuple fields.

The drawback to this method is that output schemas can't be used since they're based on the method's return type. I think that's a fair tradeoff though because the user is basically saying they want to take control themselves. We can use Annotated types to still support output schemas with CallToolResult returns.

Users will have a choice of either:

1. No return typehint, no output schema (same behavior as now)
2. CallToolResult return typehint -> no output schema.
3. Annotated[CallToolResult, SomeClass] -> SomeClass output schema

How Has This Been Tested?

MCP Inspector with a new example file

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[BrandonShar]

@felixweinberger could you add this to the Meta improvements milestone?

[maxisbey]

Related:

• feat: add tool metadata in FastMCP.tool decorator #1463
• Support for OpenAI Apps SDK #1465
• Availability of the meta parameter in tool definition on the server #1462

[maxisbey]

Thank you for the submission! I've added some code to error on registration if the function has a union type with CallToolResults as that would kinda break stuff. Also added some documentation for using this.