Package com.tnsai.tools.method

Interface ToolMethod

All Known Implementing Classes:
DynamicToolMethod, StaticToolMethod
public sealed interface ToolMethod permits StaticToolMethod, DynamicToolMethod
A tool method addressable by the LLM. Two variants:

Both variants expose enough metadata to render the JSON-Schema fragment that the LLM tool catalog needs (parametersSchema()) and to dispatch a tool call (invoke(Map, ObjectMapper)).

The interface is

invalid @link 
{@link sealed
} so ToolMethodRegistry and ToolMethodDispatcher can switch on variants without an open-class extension point — adding a new variant requires updating this permits clause and at least the dispatcher.
Since:
0.5.7 (was a record before 0.7.0; converted to sealed interface when DynamicToolMethod was added — see RFC #188 v0.7.0 closeout)

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    description()
    Human-readable description.
    boolean
    idempotent()
    Whether the tool is idempotent (safe to retry on failure, safe to cache, safe to run in parallel duplicates).
    Object
    invoke(Map<String,Object> args, com.fasterxml.jackson.databind.ObjectMapper mapper)
    Dispatch a tool call.
    default List<String>
    keywords()
    Optional discovery keywords (not exposed to the LLM).
    String
    name()
    LLM-facing tool name.
    List<ToolParameter>
    parameters()
    Parameter metadata in declaration order.
    Map<String,Object>
    parametersSchema()
    The JSON-Schema fragment for function.parameters (OpenAI) / input_schema (Anthropic).
    default boolean
    requiresConfirmation()
    Whether dispatching this tool should be gated behind an approval / confirmation filter (the AGENT-V006 safety contract).

  • Method Details

    • name

      String name()
      LLM-facing tool name. Unique per ToolMethodRegistry.

    • description

      String description()
      Human-readable description. The LLM uses this to decide when to call the tool.

    • idempotent

      boolean idempotent()
      Whether the tool is idempotent (safe to retry on failure, safe to cache, safe to run in parallel duplicates). Used as a hint by retry / fallback decorators.

    • keywords

      default List<String> keywords()
      Optional discovery keywords (not exposed to the LLM). Tool catalogs and search tools use them for fuzzy matching. StaticToolMethod surfaces the @Tool#keywords() array; DynamicToolMethod surfaces the keywords supplied to its builder (empty by default).

    • requiresConfirmation

      default boolean requiresConfirmation()
      Whether dispatching this tool should be gated behind an approval / confirmation filter (the AGENT-V006 safety contract). StaticToolMethod mirrors @Tool#requiresConfirmation(); DynamicToolMethod surfaces the flag supplied to its builder. Default false (no confirmation required) — so the agent-builder confirmation scan and any ToolCallFilter see dynamic / MCP tools that opt in, instead of only annotated @Tool POJOs (TNS-556).

    • parameters

      List<ToolParameter> parameters()
      Parameter metadata in declaration order. StaticToolMethod returns the reflected @ToolParam list; DynamicToolMethod returns empty since dynamic tools advertise their shape through parametersSchema() directly.

    • parametersSchema

      Map<String,Object> parametersSchema()
      The JSON-Schema fragment for function.parameters (OpenAI) / input_schema (Anthropic). For StaticToolMethod this is computed from parameters() via JsonSchemaGenerator; for DynamicToolMethod it is supplied at construction time.

    • invoke

      Object invoke(Map<String,Object> args, com.fasterxml.jackson.databind.ObjectMapper mapper) throws Exception
      Dispatch a tool call.
      Parameters:
      args - the LLM's argument map (Jackson-friendly: String / Number / Boolean / List / Map / null)
      mapper - a Jackson ObjectMapper for type coercion (used by StaticToolMethod to convert JSON values to the parameter's static Java type; ignored by DynamicToolMethod)
      Returns:
      the typed result for the caller to JSON-serialise back to the LLM
      Throws:
      Exception - any exception thrown by the underlying tool body