Tools Development

Tools are created by annotating methods with @Tool in classes marked with @McpService. The framework automatically discovers these methods and exposes them as callable tools.

@McpService
public class MyTools {
    @Tool(description = "Echoes a string")
    public String echoString(@ToolArg(description = "The string to be echoed") String input) {
        return input;
    }

    @Tool("customName", description = "Tool with custom name")
    public String myMethod() {
        return "result";
    }
}

Parameter Handling and Validation

Tool parameters are annotated with @ToolArg to provide metadata for validation and schema generation. Each parameter can specify a name, description, and whether it is required.

Parameter Annotation

Type Mapping

The framework automatically maps Java types to JSON Schema types:

Current limitation: although required=false is represented in the generated schema, omitted optional arguments are not yet handled correctly by the reflection invocation path. Until that is fixed, pass every annotated argument explicitly.

Example Tool Implementations

Basic String Tool

@Tool(description = "Echoes a string")
public String echoString(@ToolArg(description = "The string to be echoed") String input) {
    return input;
}

Parameterless Tool

@Tool(description = "Takes 5 seconds to complete")
public String longOperation() throws Exception {
    TimeUnit.SECONDS.sleep(5);
    return "ok";
}

Content Return Tool

@Tool(description = "A nice pic")
public ContentImage image() {
    String base64EncodedImage = ServerUtils.encodeImageToBase64("bird-eye.jpg");
    ContentImage content = new ContentImage();
    content.setMimeType("image/jpg");
    content.setData(base64EncodedImage);
    return content;
}

Multi-Content Tool

@Tool(description = "List ALL")
public List<Content> getAll() {
    List<Content> list = new ArrayList<>();
    list.add(new ContentImage(/* ... */));
    list.add(new ContentText("Hello World"));
    return list;
}