Pluggable Java-method tool-definition strategies & typed inputSchema in MCP

[andrey-fomin]

Hi @ThomasVitale,

I’ve tried to expose the REST methods of my application using MCP, but I haven’t
found an easy way to do so. I’d like to leverage Swagger v3 annotations for
tool definitions, but MethodToolCallbackProvider doesn’t support this
approach. The main issues are:

• Only @Tool annotations are considered. There’s no way to plug in an
  alternative strategy for creating tool definitions.
• Parameter names are extracted from the bytecode. Without the -parameters
  compiler flag, descriptive names aren’t available.

I propose the following enhancements:

1. Allow injection of alternative strategies for generating tool definitions
   from different kinds of method metadata. The strategy based on
   @Tool annotations could remain one of the built-in options.
2. Introduce a clear mapping between tool-definition parameter names and the
   original Java method parameters.

Moreover, implementing this parameter mapping would be much simpler if
ToolDefinition.inputSchema were a typed object (as defined in the
MCP specification)
instead of a raw JSON string. This would allow implementations to assume that
parameters in the tool definition appear in the same order as in the bytecode.

Would it be feasible to introduce these backward-incompatible changes to
ToolDefinition, MethodToolCallbackProvider, and MethodToolCallback?

Thanks!

[ThomasVitale]

@andrey-fomin thanks for raising this issue. We should definitely add some documentation and examples on how to extend and customise the tool calling strategy, because there are actually many possibilities.

Only @tool annotations are considered. There’s no way to plug in an alternative strategy for creating tool definitions.

That's not true, let me explain why. The main API to provide a tool definition+execution logic is ToolCallback. One built-in implementation is MethodToolCallback for executing Java methods as tools. Given a Java method available in a certain Java object, you can build a MethodToolCallback instance. No further constraints apply. No annotation is enforced. That should give you full flexibility to turn any Java method into a tool. See Methods as Tools: Programmatic Specification for more information.

Building on top of that API, Spring AI provides a convenient built-in strategy to source Java methods as tool candidates in a declarative way, using the @Tool annotation. That logic is provided by the MethodToolCallbackProvider, which is one implementation of the ToolCallbackProvider API. You can provide your own implementation of this API in order to support methods-as-tools using a custom annotation. The ToolCallbackProvider API is designed to give you flexibility in how tools are sourced. For example, Spring AI itself uses that API to support MCP tools. Let's consider a custom MyTool annotation. You can implement a MyToolCallbackProvider object to build MethodToolCallbacks for each method annotated with MyTool.

Parameter names are extracted from the bytecode. Without the -parameters compiler flag, descriptive names aren’t available.

The built-in MethodToolCallbackProvider relies on a default logic for building the ToolDefinition. That logic uses the parameter names for building the JSON Schema. Until recently, Spring Boot would add the -parameters compiler flag automatically when building an application. That's not true anymore: it must be added explicitly. I'll create a separate issue to document this behaviour and consider extending the tool param metadata to include a name (a suggestion already reported by someone here on GitHub, but can't find it at the moment), so to avoid that problem.

That's the built-in behaviour of MethodToolCallbackProvider, but if you implement your own ToolCallbackProvider as mentioned above, you also have full freedom in choosing how to build the ToolDefinition. Spring AI provides default implementations for many parts of the tool calling feature, but you can replace any of them with your custom ones.

I’d like to leverage Swagger v3 annotations for tool definitions, but MethodToolCallbackProvider doesn’t support this approach.

When using the built-in declarative approach to define tools (via @Tool annotation) or when using the JsonSchemaGenerator directly, Spring AI supports the Swagger v2 annotations when building the input schema in a ToolDefinition. See here and here for more information. Swagger v3 doesn't seem to exist. If you meant OpenAPI 3, then that is supported by the Swagger v2 Java library, which is what Spring AI uses as well.

I hope this answer helps clarifying some of the points raised in this issue.