Package com.tnsai.tools.method

Class ToolMethodRegistry

java.lang.Object
com.tnsai.tools.method.ToolMethodRegistry
public final class ToolMethodRegistry extends Object
Discovers and indexes Tool-annotated methods across a list of POJO tool-bearing instances.

Given a list of objects (whatever the user passes to Role.tools()), this registry scans each object's runtime class for public methods carrying @Tool, extracts their parameter metadata via ToolParam, and maintains an indexed view by tool name for fast LLM-call dispatch.

Discovery rules

  • Only public methods are scanned. Private / package-private / protected methods carrying @Tool are skipped with a debug log.
  • static methods carrying @Tool are skipped — tools are instance-level so they can carry constructor-injected dependencies.
  • If two methods (across the same or different POJOs) resolve to the same tool name, registry construction throws IllegalArgumentException — duplicate names break LLM dispatch determinism.

Parameter metadata

Parameter names are read from ToolParam.name() when set, otherwise from the reflected Parameter.getName() (which requires the -parameters compile flag — already enforced by this project's maven-compiler-plugin). Consumer projects compiling their own @Tool POJOs must enable -parameters or always set @ToolParam(name=...). A synthetic JVM name (arg0) without an explicit @ToolParam name fails registration instead of advertising garbage schema names.

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

  • Constructor Details

    • ToolMethodRegistry

      public ToolMethodRegistry(Collection<?> toolBearingObjects)
      Build a registry from a collection of POJO tool-bearing instances.
      Parameters:
      toolBearingObjects - user-supplied list (typically what Role.tools() returns)
      Throws:
      IllegalArgumentException - if two discovered tools have the same name, or if a tool is structurally invalid (blank description, etc.)

    • ToolMethodRegistry

      public ToolMethodRegistry(Collection<?> toolBearingObjects, Collection<DynamicToolMethod> dynamicTools)
      Build a registry from a collection of POJO tool-bearing instances and a list of pre-built DynamicToolMethods (e.g. from MCP proxy discovery).
      Parameters:
      toolBearingObjects - user-supplied POJOs scanned for @Tool methods
      dynamicTools - pre-built dynamic tools (proxies, runtime-defined)
      Throws:
      IllegalArgumentException - if any two registered tools (across both sources) share a name

  • Method Details

    • lookup

      public ToolMethod lookup(String name)
      Parameters:
      name - the LLM-facing tool name
      Returns:
      the tool method, or null when no such tool is registered

    • all

      public Collection<ToolMethod> all()
      Returns:
      all discovered tools in registration order

    • size

      public int size()
      Returns:
      the count of discovered tools