Proposal: reevaluate generics in the Tool API

[findleyr]

This issue summarizes some internal feedback we received about tool binding APIs. As a result of this feedback (and since handler APIs is changing in v0.3.0 anyway due to #243), we've been evaluating making some or all of the changes described below this week.

The feedback was this:

1. There must be a way to get a ToolHandler from a ToolHandlerFor[In, Out].
2. Inside of a tool handler, there should be a way to access the non-generic CallToolParams.
3. For similar reasons, there should be a way to access the non-parameterized parts of ServerRequest.

In essence, the feedback was that generics make it hard to implement aspect-oriented handling of requests, at various stages in the handling pass. Also, generics can be hard to parse visually. I think this feedback is probably right, though we may not act on all suggestions.

Notably, this is more similar to the original design, where typed tool handlers simply accepted an input struct, but we evolved toward *CallToolParamsFor[T] and then *ServerRequest[*CallToolParamsFor[T]] in #243. The feedback was essentially that this evolution toward generic structs is problematic.

Here are the changes that we're considering:

• Add a function to get the *Tool and ToolHandler that are internally created by mcp.AddTool[In, Out].
• Move the In and Out types to function parameters on ToolHandlerFor[In, Out], rather than parameterizing CallToolParams.
• Move ServerRequest into an embedded field of feature-specific request types. (This is incidentally similar to mcp-go, which would be a nice alignment).

type CallToolRequest struct {
  ServerRequest
  Params *CallToolParams
}

type ToolHandler func(context.Context, *CallToolRequest) (*CallToolResult, error)

type ToolHandlerFor[In, Out any] func(context.Context, *CallToolRequest, In) (*CallToolResult, Out, error)

func ToolFor[In, Out any](*Tool, ToolHandlerFor[In, Out]) (*Tool, ToolHandler) // this name could be improved

// The common usage is s.AddTool(ToolFor(tool, handler))
func (*Server) AddTool(*Tool, ToolHandler)

We like this, but still see a few problems / unanswered questions

• What is the type of CallToolParams.Arguments? any, map[string]any, and json.RawMessage all have problems, if this type is shared between client and server. CallToolParamsFor solved these problems.
• The name ToolFor is not great.
• Do we still want the mcp.AddTool(s, tool, handler) helper, if it is just a wrapper around s.AddTool(ToolFor(tool, handler))? Server.AddTool is more discoverable in documentation.

Any feedback on this change is welcome.

CC @jba @samthanawalla @rsc

[findleyr]

We realized that if we follow a similar pattern for the client-side of this, then we can keep CallToolParams.Arguments as a json.RawMessage, which is the simplest solution and optimizes for clarity on the server.

We will add argument values as an additional argument, which is symmetrical with the signature of ToolHandlerFor.

// CallTool makes a tool call to the connected server.
//
// If args is non-nil, it is marshalled into params.Arguments.
// CallTool panics if both params.Arguments and args are set.
func (*ClientSession) CallTool(ctx context.Context, params *CallToolParams, args any) (*CallToolResult, error)

In general, I expect that keeping the Arguments as a rawmessage may actually be convenient for clients, which may handle JSON their own way. But having the extra argument makes it much easier to use in user code and tests.

If we ever want to have similar convenience for structured output, we'd add

func CallTool[Out any](context.Context, *ClientSession, *CallToolParams, any) (*CallToolResult, Out, error)

[findleyr]

Let's not make the change to CallToolParams.Arguments for v0.3.0. I'll file a separate issue if we decide to do that for v1.0.0 (it should be inconsequential for most users).

[findleyr]

@andig had some feedback in #325 (comment).

I think we can probably help this with documentation, though we may also want to add something like a StructuredTool helper, to differentiate tools that have structured output from those that do not.