程序包 io.agentscope.core.tool

批注接口 ToolParam

@Target({PARAMETER,FIELD,ANNOTATION_TYPE}) @Retention(RUNTIME) @Documented public @interface ToolParam
Annotation to describe parameters of a tool method.

This annotation is required for all parameters of methods annotated with Tool (except ToolEmitter which is auto-injected). It provides metadata for generating JSON schemas that describe the tool's parameters to LLMs.

Usage Example: 


 @Tool(name = "calculate_area", description = "Calculate rectangle area")
 public double calculateArea(
     @ToolParam(name = "width", description = "Width in meters", required = true)
     double width,
     @ToolParam(name = "height", description = "Height in meters", required = true)
     double height,
     @ToolParam(name = "unit", description = "Unit of measurement", required = false)
     String unit
 ) {
     // Implementation
 }

Important Notes:

  • The name attribute is required because Java does not preserve parameter names at runtime by default
  • Parameter names should follow snake_case convention for LLM compatibility
  • Descriptions help the LLM understand what values to provide
  • ToolEmitter parameters do not need this annotation (they are framework-injected)
另请参阅:

  • 必需元素概要

    所需元素
    修饰符和类型
    必需的元素
    说明
    String
    name
    The name of the tool parameter.

  • 可选元素概要

    可选元素
    修饰符和类型
    可选元素
    说明
    String
    description
    The description of this parameter.
    boolean
    required
    Whether this parameter is required.

  • 元素详细资料

    • name

      String name
      The name of the tool parameter.

      This attribute is required because Java does not preserve parameter names at runtime by default (unless compiled with -parameters flag, which is not reliable). The toolkit uses this name to map LLM-provided arguments to method parameters.

      Names should follow snake_case convention (e.g., "file_path", "max_results") for compatibility with various LLM providers.

      返回:
      The parameter name as it should appear in the tool schema

    • required

      boolean required
      Whether this parameter is required.

      Required parameters must be provided by the LLM when invoking the tool. Optional parameters can be omitted, and the method will receive null (for objects) or default values (for primitives).

      返回:
      true if required (default), false if optional
      默认值:
      true

    • description

      String description
      The description of this parameter.

      This description is sent to the LLM as part of the tool schema to help it understand:

      • What this parameter represents
      • What format or values are expected
      • Any constraints or validation rules

      Good descriptions improve the LLM's ability to provide correct parameter values.

      返回:
      The parameter description, or empty string if not provided
      默认值:
      ""