Embabel Agent Documentation/com.embabel.agent.api.annotation/UnfoldingTools

UnfoldingTools

@Target(allowedTargets = [AnnotationTarget.CLASS])

annotation class UnfoldingTools(val name: String, val description: String, val removeOnInvoke: Boolean = true, val categoryParameter: String = "category", val childToolUsageNotes: String = "")

Marks a class as an UnfoldingTool container for progressive tool disclosure.

When applied to a class containing @LlmTool methods, creates a facade tool that exposes those methods when invoked. This enables progressive tool disclosure, reducing the initial tool set complexity for the LLM.

Example - Simple facade:

@UnfoldingTools(
    name = "database_operations",
    description = "Database operations. Invoke to see specific tools."
)
public class DatabaseTools {

    @LlmTool(description = "Execute a SQL query")
    public QueryResult query(String sql) { ... }

    @LlmTool(description = "Insert a record")
    public InsertResult insert(String table, Map<String, Object> data) { ... }
}

// Create the UnfoldingTool
UnfoldingTool tool = UnfoldingTool.fromInstance(new DatabaseTools());

Example - Category-based selection:

@UnfoldingTools(
    name = "file_operations",
    description = "File operations. Pass category to select tools."
)
public class FileTools {

    @LlmTool(description = "Read file contents", category = "read")
    public String readFile(String path) { ... }

    @LlmTool(description = "List directory", category = "read")
    public List<String> listDir(String path) { ... }

    @LlmTool(description = "Write file", category = "write")
    public void writeFile(String path, String content) { ... }

    @LlmTool(description = "Delete file", category = "write")
    public void deleteFile(String path) { ... }
}

// Creates a category-based UnfoldingTool automatically
UnfoldingTool tool = UnfoldingTool.fromInstance(new FileTools());

Properties

categoryParameter

val categoryParameter: String

Name of the category parameter if using category-based selection. Only used when @LlmTool methods have category specified. Default is "category".

childToolUsageNotes

val childToolUsageNotes: String

Optional usage notes to guide the LLM on when and how to use the child tools. These notes are included in the context tool created when the UnfoldingTool is invoked.

description

val description: String

Description of the UnfoldingTool. Should explain what category of tools this contains and instruct the LLM to invoke it to see specific options.

name

val name: String

Name of the UnfoldingTool facade. This is the tool name the LLM will see initially.

removeOnInvoke

val removeOnInvoke: Boolean = true

Whether to remove this tool after invocation. Default is true - the facade is replaced by its inner tools. Set to false to keep the facade available for re-invocation.

UnfoldingTools

See also

Properties