Package dyntabs.ai.annotation

Annotation Interface EasyTool

@Target(METHOD) @Retention(RUNTIME) public @interface EasyTool
Marks a method as a tool the AI is allowed to call, and (optionally) describes it.

This annotation is the gate. Since 3.0.0, EasyAI exposes tools on an opt-in basis: when you pass a service to withTools(...), only the methods you annotate with @EasyTool are visible to the model. Everything else — including state-mutating methods like cancelOrder, processPayment, or deleteUser — stays invisible and uncallable.

Why the flip (the "confused deputy" problem): a tool channel is reachable by the model, whose input is not fully trusted (think prompt injection). If every public method were exposed, a manipulated model could invoke anything on the beans you handed it, acting with your application's authority but off your script. Opt-in means adding a method is safe by default — it does nothing until you deliberately annotate it. Think of it like a restaurant menu: the kitchen can cook many things, but guests may only order what's printed on the menu. @EasyTool is what puts a method on the menu.

Exposing a method (description optional)


 public class OrderService {

     // On the menu. No description -> the AI sees tool name="findOrder", description="findOrder".
     @EasyTool
     public String findOrder(String orderId) {
         return orderRepo.findById(orderId).toString();
     }

     // On the menu, with a description that helps the AI decide WHEN to call it.
     @EasyTool("Cancels an active order. Only works for orders not yet shipped.")
     public String cancelOrder(String orderId) { ... }

     // NOT annotated -> invisible to the model. Cannot be invoked, ever.
     public void deleteAllOrders() { ... }
 }

Escape hatch (prototypes only)

If you truly want the old "expose every public method" behavior — e.g. a throwaway prototype where nothing is sensitive — use the deliberately verbose AssistantBuilder.withAllPublicMethodsAsTools(Object...) instead of withTools(...). Its name is meant to make the risk obvious at the call site.

Tips for good descriptions

  • Explain what it does and when to use it.
  • Add one when the method name alone is ambiguous, or the AI keeps picking the wrong method.
  • Especially useful to disambiguate several similar methods.
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    value
    An optional human-readable description of what the tool method does.

  • Element Details

    • value

      String value
      An optional human-readable description of what the tool method does. When present, it is sent to the AI model to help it decide when to call this method; when omitted (blank), the method name is used as the description.

      Good descriptions explain what the method does and when to use it:

      • "Finds an order by its ID and returns order details including status and items"
      • "Cancels an active order. Only works for orders that have not been shipped yet."
      • "Returns the current weather for a given city name"
      Returns:
      the tool description, or an empty string to fall back to the method name
      Default:
      ""