Embabel Agent Documentation/com.embabel.agent.api.tool/MatryoshkaTool

MatryoshkaTool

interface MatryoshkaTool : Tool

A tool that contains other tools, enabling progressive tool disclosure.

Named after Russian nesting dolls, a MatryoshkaTool presents a high-level description to the LLM. When invoked, its inner tools become available and (optionally) the MatryoshkaTool itself is removed.

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

Example:

val databaseTool = MatryoshkaTool.of(
    name = "database_operations",
    description = "Use this to work with the database. Invoke to see specific operations.",
    innerTools = listOf(queryTableTool, insertRecordTool, updateRecordTool)
)

See also

MatryoshkaToolInjectionStrategy

Types

object Companion

Properties

abstract val definition: Tool.Definition

Tool definition for LLM

abstract val innerTools: List<Tool>

The inner tools that will be exposed when this tool is invoked.

open val metadata: Tool.Metadata

Optional metadata

open val removeOnInvoke: Boolean

Whether to remove this MatryoshkaTool after invocation.

Functions

abstract fun call(input: String): Tool.Result

Execute the tool with JSON input.

open fun selectTools(input: String): List<Tool>

Select which inner tools to expose based on invocation input.

toSpringToolCallback

fun Tool.toSpringToolCallback(): <Error class: unknown class>

Extension function to convert an Embabel Tool to a Spring AI ToolCallback.

fun Tool.unwrap(): Tool

Unwrap a tool to find the innermost implementation. Recursively unwraps DelegatingTool wrappers.

inline fun <T : Tool> Tool.unwrapAs(): T?

Unwrap a tool to find a specific type, or return null if not found.

withEventPublication

fun Tool.withEventPublication(agentProcess: AgentProcess, action: Action?, llmOptions: <Error class: unknown class>): Tool

Extension function to wrap a Tool with event publication.