Task: Add Structured Tool Output Support

[ezynda3]

Priority: High
Breaking Change: No (backward compatible)

Description: Tools can now specify an outputSchema and return structured content via structuredContent field.

Implementation Tasks:

• Add OutputSchema field to Tool struct
• Add StructuredContent field to CallToolResult struct
• Implement JSON schema validation for structured content
• Update tool registration to support output schemas
• Add helper functions for creating structured tool results
• Update examples to demonstrate structured output
• Add tests for schema validation

Files to Update:

• mcp/tools.go
• mcp/types.go
• server/server.go
• Add new validation utilities

[davidleitw]

Hello @ezynda3

I noticed that this issue is currently open and doesn't appear to be assigned. May I ask if anyone is actively working on it at the moment?

If not, I would be interested in contributing. We're currently exploring structured tool outputs for our own project, so this would be a meaningful and timely opportunity to get involved.

Please let me know if it would be alright for me to take this on. I'd be happy to align on any design considerations or implementation details before starting.

If it's alright, I can start working on a draft PR later this week.

Thank you!

[ezynda3]

Yes please!

[pottekkat]

I'm trying this out at work as well, moving this to high priority as this will significantly improve how clients/hosts treat the tool result. Thanks for picking it up @davidleitw , feel free to discuss how you plan to design the API or open a draft PR while you work on it. Happy to help.

[davidleitw]

Hi @pottekkat!

Here are the changes I'm planning for structured tool outputs based on the task description:

Core Changes

1. Add OutputSchema to Tool struct

type Tool struct {
    // existing fields...
    OutputSchema ToolOutputSchema `json:"outputSchema,omitempty"`  // no pointer
}

type ToolOutputSchema struct {
    Type       string         `json:"type"`
    Properties map[string]any `json:"properties,omitempty"`
    Required   []string       `json:"required,omitempty"`
}

2. Add StructuredContent to CallToolResult

type CallToolResult struct {
    Result
    Content           []Content `json:"content"`
    StructuredContent any       `json:"structuredContent,omitempty"`  // new field
    IsError           bool      `json:"isError,omitempty"`
}

3. Add detection method

func (t Tool) HasOutputSchema() bool {
    return t.OutputSchema.Type != ""
}

JSON Schema Validation

Server-side (primary)

Add validation in handleToolCall() - this ensures protocol compliance before sending data.

Client-side (optional)

Add optional validation in client code for debugging/monitoring purposes. This would be configurable and mainly useful during development.

API Changes

4. Add WithOutput* functions

I considered a few approaches for this:

Option 1: Schema Target with enum

WithStringProperty(InputSchemaTarget, "location", opts...)
WithStringProperty(OutputSchemaTarget, "result", opts...)

This would be more flexible but requires changing the existing API signature.

Option 2: Schema Builder pattern

outputSchema := NewSchemaBuilder("object").
    AddString("temperature", Description("temp")).
    Build()
tool := NewTool("weather", WithOutputSchema(outputSchema))

More powerful but quite different from the current functional options pattern.

Option 3: Parallel WithOutput functions*

WithString("location", Required())     // existing, for input
WithOutputString("result", Required()) // new, for output

I think Option 3 is the way to go because:

• Zero breaking changes to existing code
• Maintains the same familiar API pattern
• Clear semantic distinction between input/output
• Can reuse all existing PropertyOption functions

The downside is some code duplication, but I think the backward compatibility benefit outweighs that.

5. Helper functions for creating structured results

• NewStructuredToolResult(structuredContent, textContent...)
• NewValidatedStructuredResult(content, schema)
• Extend existing NewToolResult* functions to support structured content

6. Update tool registration

Server will need to handle tools with output schemas during registration and store schema info for validation.

Implementation Tasks Coverage

• ✅ Add OutputSchema field to Tool struct
• ✅ Add StructuredContent field to CallToolResult struct
• ✅ Implement JSON schema validation for structured content
• ✅ Update tool registration to support output schemas
• ✅ Add helper functions for creating structured tool results
• ✅ Update examples to demonstrate structured output
• ✅ Add tests for schema validation

Files to modify

• mcp/tools.go - Tool struct + WithOutput* functions + CallToolResult struct
• server/server.go - validation logic + tool registration updates
• mcp/validation.go - new file for JSON schema validation
• mcp/utils.go - helper functions
• examples/ - updated examples
• Tests for all new functionality

I'm planning to start working on this within the next two days and will open a draft PR with the initial implementation.

If there's anything I haven't considered or any concerns about the approach, please let me know - would appreciate any feedback before I dive into the code!

[pottekkat]

Thanks for the detailed response, I will respond tomorrow after checking.