Package com.embabel.agent.api.tool.progressive

Interface UnfoldingTool

  • All Implemented Interfaces:
    com.embabel.agent.api.tool.Tool , com.embabel.agent.api.tool.ToolInfo , com.embabel.agent.api.tool.progressive.ProgressiveTool 
    
public interface UnfoldingTool
 implements ProgressiveTool

    A ProgressiveTool with a fixed set of inner tools that are revealed when invoked, regardless of the agent process context.

    This pattern is useful for:

    • Reducing tool set complexity for the LLM

    • Grouping related tools under a category facade

    • Progressive disclosure based on LLM intent

    When an UnfoldingTool is expanded, a context tool can be created that preserves the parent's description and optional usage notes. This solves the problem where child tools would lose context about the parent's purpose.

    The childToolUsageNotes field provides additional guidance on how to use the child tools, included only once in the context tool rather than duplicated in each child tool's description.

    Example:

    val spotifyTool = UnfoldingTool.of(
    name = "spotify_search",
    description = "Search Spotify for music data including artists, albums, and tracks.",
    innerTools = listOf(vectorSearchTool, textSearchTool, regexSearchTool),
    childToolUsageNotes = "Try vector search first for semantic queries like 'upbeat jazz'. " +
        "Use text search for exact artist or album names. " +
        "Use regex search for pattern matching on metadata."
)

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      public class UnfoldingTool.Factory

      Factory methods for creating UnfoldingTool instances. This is an open class so that subinterface companions can extend it.
      public class UnfoldingTool.Companion

    • Field Summary

      Fields 
      Modifier and Type Field Description

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Constructor Detail

    • Method Detail

      • selectTools

         List<Tool> selectTools(String input)

        Select which inner tools to expose based on invocation input.

        Override this method to implement category-based or argument-driven tool selection. Default implementation returns all inner tools.

        Parameters:
        input - The JSON input string provided to this tool
        Returns:

        The tools to expose (subset of innerTools or all)

      • withTools

         UnfoldingTool withTools(Tool tools)

        Create a new UnfoldingTool with additional tools added.

        This enables fluent building of tool groups:

        val combined = UnfoldingTool.of("tools", "My tools", listOf(baseTool))
    .withTools(searchTool, filterTool)
    .withToolObject(HelperTools())
        Parameters:
        tools - The tools to add
        Returns:

        A new UnfoldingTool with the combined tools

      • withToolObject

         UnfoldingTool withToolObject(Object toolObject)

        Create a new UnfoldingTool with tools added from an annotated object.

        The object should have methods annotated with @LlmTool. This enables fluent building of tool groups:

        val combined = UnfoldingTool.of("tools", "My tools", listOf(baseTool))
    .withToolObject(DatabaseTools())
    .withToolObject(FileTools())
        Parameters:
        toolObject - An object with @LlmTool annotated methods
        Returns:

        A new UnfoldingTool with the combined tools

      • getInnerTools

         abstract List<Tool> getInnerTools()

        The inner tools that will be exposed when this tool is invoked. This is a fixed set that does not vary by context.