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

MatryoshkaTools

@Target(allowedTargets = [AnnotationTarget.CLASS])
annotation class MatryoshkaTools(val name: String, val description: String, val removeOnInvoke: Boolean = true, val categoryParameter: String = "category")

Marks a class as a MatryoshkaTool container.

When applied to a class containing @LlmTool methods, creates a facade tool that exposes those methods when invoked. This enables progressive tool disclosure.

Example - Simple facade:

@MatryoshkaTools(
    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 MatryoshkaTool
MatryoshkaTool tool = MatryoshkaTool.fromInstance(new DatabaseTools());
Content copied to clipboard

Example - Category-based selection:

@MatryoshkaTools(
    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 MatryoshkaTool automatically
MatryoshkaTool tool = MatryoshkaTool.fromInstance(new FileTools());
Content copied to clipboard

See also

Properties

Link copied to clipboard
val categoryParameter: String

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

Link copied to clipboard
val description: String

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

Link copied to clipboard
val name: String

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

Link copied to clipboard
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.