Enhancement: Add validation for tool schema generation at registration time

[andylbrummer]

Enhancement: Add validation for tool schema generation at registration time

Summary

The MCP Go SDK should validate that tool input/output struct fields have sufficient type information for JSON schema generation when tools are registered, rather than failing silently until MCP Inspector validates the schemas.

Problem

Currently, when using mcp.AddTool() with struct fields that have ambiguous types like interface{} or map[string]interface{}, the SDK generates invalid JSON schemas but doesn't report any errors. The issue only becomes apparent when:

1. An MCP Inspector validates the tool schemas
2. A client attempts to use the tool and gets validation errors

This creates a poor developer experience with confusing, delayed error messages.

Current Behavior

// This compiles and registers successfully, but generates invalid schema
type SnapshotOutput struct {
	Success bool        `json:"success"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`  // No error!
}

mcp.AddTool(server, &mcp.Tool{
	Name: "snapshot",
	Description: "...",
}, handler) // No error at registration

When validated by MCP Inspector:

{
  "error": "[{\"code\":\"custom\",\"path\":[\"tools\",8,\"outputSchema\",\"properties\",\"data\"],\"message\":\"Invalid input\"}]"
}

Expected Behavior

The SDK should validate schemas during mcp.AddTool() and fail fast with a clear error:

panic: Tool 'snapshot' registration failed: output schema validation error
  Field 'Data' has type 'interface{}' which cannot be represented in JSON Schema

  Solution: Add a jsonschema tag to provide type hints:
    Data interface{} `json:"data,omitempty" jsonschema:"oneof_type=object;array"`

  Or use a concrete type instead of interface{}

Suggested Implementation

Add schema validation in the tool registration process:

1. When mcp.AddTool() is called, validate the generated JSON schema
2. Check for problematic types:
   • interface{} without jsonschema tags
   • map[string]interface{} without jsonschema tags
   • Other types that produce ambiguous schemas
3. Provide actionable error messages with suggested fixes

Example Fix

// Valid: Provides schema hints
type SnapshotOutput struct {
	Success bool        `json:"success"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty" jsonschema:"oneof_type=object;array"`
}

// Also valid: Uses concrete type
type LogEntryOutput struct {
	Type      string                 `json:"type"`
	Timestamp time.Time              `json:"timestamp"`
	Data      map[string]interface{} `json:"data" jsonschema:"type=object"`
}

Impact

This enhancement would:

• Catch schema errors at compile/startup time instead of runtime
• Provide clear, actionable error messages
• Improve developer experience
• Prevent invalid MCP servers from running

Related Issues

• Validation of MCP tool Name property #169 - Validation of MCP tool Name property (validates regex at runtime)
• No tools are advertised when assigning a pointer type in the generic for CallToolResultFor #200 - Issues with pointer types in generics
• Proposal: reevaluate generics in the Tool API #327 - Proposal to reevaluate generics in Tool API

Workaround

Until this is implemented, developers must:

1. Test with MCP Inspector after every schema change
2. Manually add jsonschema tags to all interface{} and map[string]interface{} fields
3. Hope runtime validation catches issues before production

---

Environment:

• go-sdk version: latest (main branch)
• Go version: 1.24.2
• Discovered while implementing: https://github.com/standardbeagle/agnt

[findleyr]

I agree that this would be good, and I wish we were stricter about this initially.

How would you expect the errors to be served? We can't change AddTool to return an error, and a panic would (at least theoretically) be a breaking change.