Use a single parameter to represent the tool request object

[anthony-c-martin]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

I currently have code that looks like the following:

[McpServerToolType]
public static class MyTools
{
    [McpServerTool, Description("Tool description ...")]
    public static async Task<string> ToolMethod1(
        [Description("Parameter 1 description ...")]
        string parameter1,
        [Description("Parameter 2 description ...")]
        string parameter2,
        [Description("Parameter 3 description ... Optional.")]
        List<MyParamType>? parameter3Optional = null)
    {
        // Some processing ...
    }
}

What I'd really like to be able to write is something like the following, where "request" represents the full payload body schema, rather than a parameter named "request", which would be the default behavior:

[McpServerToolType]
public static class MyTools
{
    [McpServerTool, Description("Tool description ...")]
    public static async Task<string> ToolMethod1(ToolMethod1Request request)
    {
        // Some processing ...
    }
}

public class ToolMethod1Request
{
    [Description("Parameter 1 description ...")]
    public required string parameter1 { get; set; }

    [Description("Parameter 2 description ...")]
    public required string parameter2 { get; set; }

    [Description("Parameter 3 description ... Optional.")]
    public List<MyParamType>? parameter3Optional { get; set; }
}

The benefit of this approach is that the code declaring the schema the "top-level" request can be authored similarly to the code for types in nested properties.

Is this something that's possible today?

[stephentoub]

Is this something that's possible today?

That should "just work". Does it not? Parameters can be complex, so there's nothing preventing a parameter to your method itself having multiple properties.

Is there something more subtle you're asking for? e.g. is it that you want to write it with such a XxRequest class but have the schema be more like for individual parameters, and if so, why?

[anthony-c-martin]

Sorry, I didn't explain myself very clearly!

The first example results in an input schema that looks like:

{
  "properties": {
    "parameter1": {...},
    "parameter2": {...},
    "parameter3Optional": {...}
  }
}

The second example results in an input schema that looks like:

{
  "properties": {
    "request": {
      "properties": {
        "parameter1": {...},
        "parameter2": {...},
        "parameter3Optional": {...}
      }
    }
  }
}

What I'd like to do is write C# that looks like the 2nd example, but produces a schema like the 1st example.

[PederHP]

So basically an "explode" attribute? That'd map between a request object and top-level request properties? That does make sense, as LLMs tend to work better with all top-level properties, but it can give some awful signatures. The way I usually handle this is just to map from the annotated tool-exposing method to an implementation with a nicer interface. That's a good pattern in general, I think - as it means you can change tool and implementation signatures - for whatever reason, without affecting the other.

I see your point, but is it really that bad to do the first version and then call with a new(prop1, prop2, prop3) as the argument to the implementation? In general you don't want a ton of tools anyway (at least not with current models), so it's not like you'll have to write this again and again.

[anthony-c-martin]

Thanks, your understanding is correct. It's definitely a convenience feature, not a blocker. Personally I'd just like consistency between annotating request classes and classes referenced by request classes with descriptions, and it makes stuff like building a request for testing a little more convenient.