Tool binding APIs

[findleyr]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Tool binding is one of the most nuanced areas of the MCP SDK design. The design doc has a survey of options. I'm opening this discussion to collect feedback and share ideas.

See that doc for details, but to summarize: we considered a spectrum of binding APIs, and settled for a middle ground that uses a combination of generics and reflection to handle automatic marshaling of input and validation of input schemas (and eventual output, once we add support for output schema), along with options to modify the schema, which are primarily used to set descriptions.

type ToolHandlerFor[In, Out any] func(context.Context, *ServerSession, *CallToolParamsFor[In]) (*CallToolResultFor[Out], error)

func NewServerTool[In, Out any](name, description string, handler ToolHandlerFor[In, Out], opts ...ToolOption) *ServerTool

Additionally, users can always create a tool 'manually' by constructing a ServerTool literal with a non-generic ToolHandler.

However, there are a few potential problems with these APIs that could warrant changes:

• It is unfortunate that the binding using reflection has no way to set the description of the tool properties. This means that descriptions are added far away from the type definition.
• The names NewServerTool (and ServerTool) could be improved: isn't a 'ServerTool' just a 'Tool'?

Alternatives

We are considering several alternatives / extensions to the APIs above.

• Support an mcp struct tag to allow specifying property descriptions in the tool parameter struct. The downside of this is that descriptions are limited in their verbosity, and static.

type HiParams struct {
  Name string `json:"name" mcp:"the name of the person to greet"`
}

• Use codegen and //mcp:description ... comments to read the description from the doc string. This requires an extra step, and still has the same problem that descriptions are static.

type HiParams struct {
  // Name is the person to greet.
  //mcp:description the name of the person to greet
  Name string `json:"name"`
}

• Add more ergonomic ToolOptions, to simplify mcp.Input(mcp.Property("p", mcp.Description("the description"))). For example the above could be shortned to mcp.Describe("p", "the description").

After using them a bit, what do folks think about these APIs? Can/should they be improved?

CC @jba @hyangah @SamMorrowDrums

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[qiaodev]

I like the alternative options more than the current generics and reflection approach. When I looked at the interface, I was quite confused about what I would get from the reflection and what ToolOption (like description) I needed to input.

I guess the reflection won't set function parameter names, so I may need to add function parameter names through additional input?

I also want to constrain the minimum and maximum values for some function parameters, but how can I configure this using the ToolOption? The min/max value for the field is a nested field. It's hard to write the correct JSON schema together with the schema generated from reflection.

Besides, I want to specify the property ordering because some properties have dependencies on each other, and I want the model to generate the parent parameter value first.

Stepping back, if you do nothing and just exposed a simple struct rather than the ToolOption interface, my life would be much easier. Take this struct schema as an example (from googleapis/go-genai#336):

schema := &genai.Schema{
			Type:     genai.TypeArray,
			MaxItems: aws.Int64(70),
			MinItems: aws.Int64(70),
			Items: &genai.Schema{
				Type: genai.TypeObject,
				Properties: map[string]*genai.Schema{
					"type":        {Type: genai.TypeString},
					"question":    {Type: genai.TypeString},
					"options":     {Type: genai.TypeArray, Items: &genai.Schema{Type: genai.TypeString}},
					"answer":      {Type: genai.TypeString},
					"explanation": {Type: genai.TypeString},
				},
				Required:         []string{"type", "question", "answer"},
				PropertyOrdering: []string{"type", "question", "options", "answer", "explanation"},
			},
		}

The current design has a learning curve. I am still struggling to translate this to ToolOption...

[findleyr]

Thanks. I think we need a concrete proposal for the interface approach, because I think there are some unsolved problems. For example, if we're going to allow the input type and output type to own the schema generation, then we need an actual value on which to call Schema(). This means we need to either pass in a value during tool binding, or use generics and call Schema on the zero value. Both of those are a little odd.

@jba is going to revisit this, because he ran into the same category of problem in #20. We need to rethinking how schemas are controlled.

[SamMorrowDrums]

I got super close to concrete proposal but still ironing out a couple of kinks. Will be good to have something to poke holes in though. Tomorrow is a realistic target.

[SamMorrowDrums]

@findleyr I got as far as I could. Anyone is welcome to rif on this: #57

But at least I got a fully working build.

[SamMorrowDrums]

A rough look at the most basic implementation:

type HiArgs struct {
	Name string `json:"name"`
}

func (h *HiArgs) Schema() (*jsonschema.Schema, error) {
	return jsonschema.For[HiArgs]()
}

func (h *HiArgs) SetParams(raw json.RawMessage) error {
	return json.Unmarshal(raw, h)
}

type HiResult struct {
	Message string
}

func (h *HiResult) Result() (*mcp.CallToolResult, error) {
	return &mcp.CallToolResult{
		Content: []mcp.Content{
			&mcp.TextContent{Text: h.Message},
		},
	}, nil
}

[SamMorrowDrums]

This means we need to either pass in a value during tool binding, or use generics and call Schema on the zero value. Both of those are a little odd.

I think it's not that gross (although quirky may be fair characterization):

func newServerToolErr[In ToolInput, Out ToolOutput](name, description string, handler ToolHandlerFor[In, Out], opts ...ToolOption) (*ServerTool, error) {
	// instantiate zero value of In type
	var in In
	ischema, err := in.Schema()

[jba]

Question: what other features of JSON Schema do you use?

@qiaodev You said, "I also want to constrain the minimum and maximum values for some function parameters." Is that a common thing? The "null hypothesis" is that only the property types, description and required bit are used.

[qiaodev]

Is that a common thing?

Businesses may need to constrain function parameter values within a specific range. See googleapis/go-genai#336

When triaging GenAI issues, I've found that property_ordering comes up more often than min/max values.

[jba]

When triaging GenAI issues, I've found that property_ordering comes up more often than min/max values.

That's a problem, because propertyOrdering is not in JSON Schema.
https://ai.google.dev/gemini-api/docs/structured-output#property-ordering
"When you're working with JSON schemas in the Gemini API, the order of properties is important."

JSON doesn't have a concept of ordered properties, so JSON Schema doesn't either.
We'll need another way to deal with this. I really don't want to make the jsonschema package anything other than JSON Schema.

[jba]

I think this aspect of the schema is a client-side issue, from MCP's point of view. That is, I assume the flow looks like:

1. MCP client calls ListTools on the server
2. MCP client gives those tools to the LLM
3. LLM asks to call a tool
4. MCP client sends CallTool to the server.

In step 2, a Gemini client will have to translate mcp.Tool to genai.Tool (or whatever it's called). Part of that is translating the schema, and then it can add property ordering. As far as I can tell, property ordering has no effect (indeed, can have no effect, since maps are unordered) on schema validation. Its only purpose is to align the schema with any provided examples:

If you're providing examples to the model with a schema configured, and the property ordering of the examples is not consistent with the property ordering of the schema, the output could be rambling or unexpected. (Gemini doc).

I guess that's a client issue, unless there are server-provided prompts involved. Then there needs to be coordination between prompts and tool schemas, which is out of scope of the MCP spec.

[jba]

I really don't want to make the jsonschema package anything other than JSON Schema.

Actually, JSON Schema is extensible: you can define new keywords. I suppose I do need a way to handle that.

[jba]

Filed #69 for additional JSON Schema keywords.

[jba]

Alternative API for adding tools: #73.
@qiaodev does this address your issues?

[qiaodev]

This addressed my issues. Thanks for making the redesign!

[mhpenta]

Descriptions for parameters in field tags works great in the majority of cases, imo.

This works, in part, because you can use the tool’s overall description to refine the LLM’s understanding rather than making the field tags unruly. So the field tags' description and the tool description work in concert.

Calling it "mcp" is a little confusing, I wonder if we might just go with "description" or "desc."

We do need the escape hatch as discussed above but I have no opinion on #57 atm.

[jba]

"description" or "desc" seem a little broad. By convention, the tag names are scoped to the system; otherwise we could be stepping on a name used by something else. I think "mcp" is OK. The main problem is future-proofing if we want to add more things, but even then we could treat the description as being the last thing.

What I mean is, if you have:

`mcp:"the name to use"`

and later we add, say, the ability to set minLength, we could write that as

`mcp:"minLength=4,the name to use"`

That would only break if a description started "foo=bar", which seems quite unlikely.

[mhpenta]

Understand the need to keep the field tags scoped to the system.

I am wondering if it might be best to call it "jsonschema" or similar instead, since these tags modify directly the schema being generated and since that package might be broken out.

I am thinking about the case of a system with both a non-MCP tool system and a MCP tool system. We might run into unergonomic situations like this:

type SearchManagerParams struct {
	SearchTerm  string `json:"searchTerm" jsonschema:"description=Search query term or phrase to find in documents" mcp:"Search query term or phrase to find in documents"`
	N           int    `json:"n" jsonschema:"description=Maximum number of search results to return. Recommended: 5 (quick overview), 10-15 (standard research), 20+ (comprehensive analysis)" mcp:"Maximum number of search results to return. Recommended: 5 (quick overview), 10-15 (standard research), 20+ (comprehensive analysis)"`
	SortByScore bool   `json:"sortByScore" jsonschema:"description=Sort results by relevance score (recommended for most searches)" mcp:"Sort results by relevance score (recommended for most searches)"`
	SortByDate  bool   `json:"sortByDate" jsonschema:"description=Sort results by document date (newest first)" mcp:"Sort results by document date (newest first)"`
}

The jsonschema tag above is what is used in invopop/jsonschema, so some systems already use it.

Or I'd have non-MCP tooling use the mcp tag as well for schema generation, which is awkward but workable.

[jba]

I think that's a good idea. Will ponder it over the weekend.
@findleyr WDYT?