Add OutputSchema declarations to tools for improved AI orchestration

[jongalloway]

Context

MCP C# SDK v1.2.0 (csharp-sdk#1425) added support for specifying OutputSchema independently of the return type for tools that return CallToolResult. This lets tools declare their JSON response shape at discovery time (in tools/list) rather than requiring clients to invoke the tool first.

Current State

All 74 tools return structured JSON via StructuredContentHelper.ToCallToolResult(), and many support a machineReadable parameter that switches between plain text and JSON output. However, clients currently have no way to know the expected response shape until they call the tool.

Proposed Change

Add OutputSchema declarations to consolidated tools so AI assistants can:

1. Understand response structure at discovery time — know what fields to expect before calling a tool
2. Better plan multi-step workflows — orchestrators can wire tool outputs together without trial invocations
3. Validate responses — clients can verify tool output conforms to the declared schema

Scope

• Consolidated tools (dotnet_project, dotnet_package, dotnet_solution, etc.) that produce structured JSON in machine-readable mode
• dotnet_server_capabilities and dotnet_server_metrics which always return JSON
• Error responses via ErrorResultFactory which follow a consistent schema

Example

[McpServerTool(Title = "Server Capabilities", ReadOnly = true, Idempotent = true,
    OutputSchema = typeof(ServerCapabilities))]
public async partial Task<CallToolResult> DotnetServerCapabilities()

Or for tools with conditional schemas based on machineReadable:

// OutputSchema represents the machine-readable JSON contract
[McpServerTool(Title = ".NET Project", OutputSchema = typeof(...),
    TaskSupport = ToolTaskSupport.Optional)]

Files

• DotNetMcp/Tools/Cli/DotNetCliTools.*.Consolidated.cs — consolidated tools
• DotNetMcp/Tools/Cli/DotNetCliTools.Misc.cs — capabilities/metrics tools
• DotNetMcp/Helpers/StructuredContentHelper.cs — response factory
• DotNetMcp/Errors/ErrorResult.cs — error response schema
• doc/machine-readable-contract.md — existing machine-readable documentation

References

• MCP C# SDK v1.2.0 release notes
• csharp-sdk#1425 — Support specifying OutputSchema independently of return type