Package akka.javasdk.annotations.mcp

Annotation Interface McpTool

@Target(METHOD) @Retention(RUNTIME) @Documented public @interface McpTool
Annotation to expose a method as an MCP tool that can be called by MCP clients.

MCP tools are functions that AI models can invoke to perform specific tasks or retrieve information. The LLM determines which tools to call based on the tool descriptions and the user's request.

Method Requirements:

  • Must be public
  • Must return a String
  • Can accept 0 or more parameters
  • Must be in a class annotated with McpEndpoint

Parameter Types: Only simple parameter types are supported. Fields must be primitive types, boxed Java primitives, or strings. All parameters are required by default; use Optional<T> for optional parameters.

Schema Generation: The input schema is automatically generated from method parameters unless a manual schema is provided via inputSchema(). Use Description annotations on parameters to help the LLM understand their purpose.

Best Practices:

  • Provide clear, descriptive tool descriptions
  • Use Description on all parameters
  • Keep tools focused on single, well-defined tasks
  • Validate input parameters for security
  • Use ToolAnnotation to describe tool behavior characteristics

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    description
     

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    ToolAnnotation[]
    annotations
    Optional annotations describing what the tool does to the client.
    String
    inputSchema
    Normally, the schema is inferred from the input parameters of the tool method.
    String
    name
     

  • Element Details

    • name

      String name
      Returns:
      The name of the tool. Must be unique in the same MCP endpoint if specified, if not specified, the method name is used.
      Default:
      ""

    • description

      String description
      Returns:
      A clear description of what the tools, used by the client LLM to determine what the tool can be used for

    • inputSchema

      String inputSchema
      Normally, the schema is inferred from the input parameters of the tool method.
      Returns:
      A manually specified schema instead of the automatic must match the input parameters and how they are parsed by Jackson.
      Default:
      ""

    • annotations

      ToolAnnotation[] annotations
      Optional annotations describing what the tool does to the client.
      Default:
      {}