Package org.mcpjava.server.tools

Annotation Interface Tool

@Target(METHOD) @Retention(RUNTIME) @Documented public @interface Tool
Marks a method as an MCP tool that can be invoked by clients.

The method will be exposed as a tool in the MCP server. The tool name can be explicitly specified via the name() attribute, or will be derived from the method name if not specified.

Parameters

Tool methods may have parameters of the following types:

  • McpRequest - to access information about the request
  • Cancellation - to allow processing to be stopped if the client cancels the tool call
  • Progress - to send progress reports back to the client
  • Implementations may define additional types that can be used as parameters
  • All other parameters are treated as arguments to the tool. In most cases these parameters must be annotated with ToolArg with the name attribute set, unless the code was compiled with the -parameters option. ToolArg also allows other properties of the argument to be configured.

Return Type Handling

The annotated method can return various types that will be converted to MCP tool responses:

  • String - Converted to a text content response
  • ContentBlock implementations - Used directly in the response
  • List of ContentBlock or String - Multiple content items in the response
  • ToolResponse - Used directly as the response
  • Other types - Encoded according to framework-specific rules (typically as JSON)
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Tool.Annotations
    Nested annotation for tool behavioral hints.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Tool.Annotations
    annotations
    Behavioral hints and annotations for this tool.
    String
    description
    A human-readable description of what the tool does.
    String
    name
    The unique name of the tool.
    Class<?>
    outputSchemaFrom
    The class to use to generate the output schema for structured content.
    boolean
    structuredContent
    If set to true, the method return value is converted to JSON and used as structured content in the result.
    String
    title
    A human-readable title for the tool.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ELEMENT_NAME
    Constant value for name() indicating that the annotated element's name should be used as-is.

  • Field Details

    • ELEMENT_NAME

      static final String ELEMENT_NAME
      Constant value for name() indicating that the annotated element's name should be used as-is.
      See Also:

  • Element Details

    • name

      String name
      The unique name of the tool.

      Each tool bound to the same MCP server configuration must have a unique name. This is intended for programmatic or logical use, but may be used for UI display as a fallback if title() is not present.

      By default, the name is derived from the annotated method name.

      Returns:
      the tool name
      Default:
      "<<element name>>"

    • title

      String title
      A human-readable title for the tool.

      This is a short, user-friendly display name for the tool.

      Returns:
      the tool title
      Default:
      ""

    • description

      String description
      A human-readable description of what the tool does.

      This description will be sent to MCP clients to help them understand when and how to use this tool. It serves as a hint to the model.

      Returns:
      the tool description
      Default:
      ""

    • annotations

      Tool.Annotations annotations
      Behavioral hints and annotations for this tool.

      These provide additional hints to clients about the tool's behavior and characteristics. Note that annotations must be declared explicitly to be included in tool metadata.

      Returns:
      the tool annotations
      Default:
      @org.mcpjava.server.tools.Tool.Annotations

    • structuredContent

      boolean structuredContent
      If set to true, the method return value is converted to JSON and used as structured content in the result.

      When enabled, the output schema is generated automatically from the return type, or from outputSchemaFrom() if set.

      Returns:
      true if structured content should be used
      See Also:
      Default:
      false

    • outputSchemaFrom

      Class<?> outputSchemaFrom
      The class to use to generate the output schema for structured content.

      If a tool returns structured content, this method can be used to override the type used to generate the output schema. This is necessary for tool methods that return ToolResponse and want to include structured content.

      By default, the output schema is generated from the method return type.

      Returns:
      the class to use to generate the output schema
      See Also:
      Default:
      java.lang.Void.class