Package com.tnsai.annotations

Annotation Interface ToolParam

@Documented @Retention(RUNTIME) @Target(PARAMETER) public @interface ToolParam
Per-parameter metadata for a Tool-annotated method.

The framework derives JSON Schema property descriptions for the LLM tool catalog from this annotation. description() is required because tool-call quality degrades sharply when the LLM lacks per-parameter context.

Usage


 @Tool(description = "Extract specific columns from a CSV file")
 public List<Map<String, String>> csvColumns(
     @ToolParam(description = "Absolute file path") String path,
     @ToolParam(description = "Column names to extract") List<String> columns
 ) { ... }

Naming

name() defaults to the reflected parameter name. The framework enforces the -parameters compile flag (already on for this project's maven-compiler-plugin), so reflection can read the parameter name at runtime. Override name() only when the LLM-facing name should differ from the Java parameter name (rare).

Since:
0.5.7 (LangChain-style tool refactor — see issue #188)
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    description
    Human-readable description surfaced to the LLM.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    defaultValue
    Default value as a string.
    String
    name
    Parameter name surfaced to the LLM.
    boolean
    required
    Whether this parameter must be present in every LLM call.

  • Element Details

    • name

      String name
      Parameter name surfaced to the LLM. Defaults to the reflected parameter name (Java method-parameter name as captured at compile time with the -parameters flag).
      Returns:
      the parameter name (empty means "use Java parameter name")
      Default:
      ""

    • description

      String description
      Human-readable description surfaced to the LLM. Required — be specific about format, units, examples. Empty descriptions are not an error but are strongly discouraged.
      Returns:
      parameter description (must be non-empty in practice)

    • required

      boolean required
      Whether this parameter must be present in every LLM call. When false, the parameter becomes optional and the framework substitutes defaultValue() (or null for reference types) when the LLM omits it.
      Returns:
      true if required (default)
      Default:
      true

    • defaultValue

      String defaultValue
      Default value as a string. Parsed to the parameter's declared static type at dispatch time using the framework's standard coercer (handles primitives, String, enums; complex types unsupported as defaults). Empty means no default.
      Returns:
      default value string ("" means no default)
      Default:
      ""