Annotation Interface P

@Retention(RUNTIME) @Target(PARAMETER) public @interface P
Annotation for parameters of a Tool-annotated method.

Description

value() and description() are aliases for the same thing: the parameter's description that the LLM will see. Use one or the other, but not both at the same time.

When only a description is needed, value can be used as a shorthand: 

@Tool
void getWeather(@P("The city name") String city) { ... }

When both a name and a description are needed, use named attributes: 

@Tool
void getWeather(@P(name = "city", description = "The city name") String city) { ... }

Name

The name() attribute overrides the parameter name that the LLM will see. This is useful in two cases:
  1. Missing -parameters javac option. Without it (common when not using frameworks like Quarkus or Spring, which enable it by default), Java reflection returns generic names such as arg0, arg1, etc. The semantic meaning of the parameter is lost, which may confuse the LLM. Setting name restores a meaningful name.
  2. Custom name for the LLM. When you want the LLM to see a different parameter name than the one the developer uses in the source code (for example, to match a specific API contract or to provide a more descriptive name).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    NO_DEFAULT
    Sentinel value for defaultValue() meaning "no default set".

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    defaultValue
    Default value to substitute when the LLM omits this argument.
    String
    description
    Description of the parameter.
    String
    name
    Name of the parameter as seen by the LLM.
    boolean
    required
    Whether the parameter is required.
    String
    value
    Description of the parameter.

  • Field Details

    • NO_DEFAULT

      static final String NO_DEFAULT
      Sentinel value for defaultValue() meaning "no default set". Lets the framework distinguish between "the developer did not specify a default" and "the default is an empty string".
      See Also:

  • Element Details

    • name

      String name
      Name of the parameter as seen by the LLM.

      If not specified, the actual method parameter name is used (requires the -parameters javac option; otherwise the name defaults to arg0, arg1, etc.).

      Setting this is useful when:

      • The -parameters javac option is not enabled and you want to avoid generic arg0/arg1 names. Note that frameworks like Quarkus and Spring enable -parameters by default, so you typically do not need to set name when using those frameworks.
      • You want the LLM to see a different name than the one in the source code.
      Returns:
      the name of the parameter
      Default:
      ""

    • description

      String description
      Description of the parameter. This is an alias for value(). Use either value or description, but not both.
      Returns:
      the description of the parameter
      Default:
      ""

    • value

      String value
      Description of the parameter. This is an alias for description(). Use either value or description, but not both.

      Convenient for the shorthand form: @P("description here").

      Returns:
      the description of the parameter
      Default:
      ""

    • required

      boolean required
      Whether the parameter is required. Default is true.

      The required flag controls the JSON schema sent to the LLM: required parameters are listed in the schema's required array. The LLM is expected to honour this, but in practice it can disregard the schema and omit an argument anyway.

      1.x behaviour when a required argument is missing:

      • Primitive parameters (int, long, boolean, …) — detected and surfaced as a ToolArgumentsException.
      • Object parameters — not validated; null is passed to the Tool-annotated method, even though the schema marked the parameter as required.
      We are planning to remove this asymmetry in LangChain4j 2.0 so that all required arguments are validated uniformly. If this planned change would affect your use case, please open an issue at github.com/langchain4j/langchain4j/issues so we can hear your feedback before it lands.
      Returns:
      true if the parameter is required, false otherwise
      Default:
      true

    • defaultValue

      String defaultValue
      Default value to substitute when the LLM omits this argument.

      Setting a default value is equivalent to setting required() to false: the parameter is marked as optional in the JSON schema sent to the LLM (it is not added to the schema's required array). When the LLM omits the argument, the framework substitutes this default at runtime instead of passing null (or, for primitives, throwing).

      The string is parsed at AI Service registration time according to the parameter's type:

      • String parameters: used verbatim.
      • Primitives, boxed primitives, enums, BigDecimal, BigInteger, UUID: parsed via type-specific conversion.
      • Collections, maps, POJOs: parsed as JSON (e.g. "[]", "{\"name\":\"foo\"}").
      If the value cannot be parsed into the parameter's type, AI Service construction fails with exception.

      Restrictions:

      • Cannot be combined with Optional<T> parameters (Optional already represents "absent"; pick one mechanism).
      • Cannot be set on framework-injected parameters (@ToolMemoryId and similar).
      Returns:
      the default value as a string, or NO_DEFAULT if not set
      Default:
      "\u0000__LANGCHAIN4J_NO_DEFAULT__\u0000"