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

MatryoshkaTool

interface ~~MatryoshkaTool~~ : UnfoldingTool

Deprecated

Use UnfoldingTool instead

Replace with

import com.embabel.agent.api.tool.progressive.UnfoldingTool

UnfoldingTool

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.

See also

UnfoldingToolInjectionStrategy

Types

object Companion : UnfoldingTool.Factory

Companion object that extends UnfoldingTool.Factory to provide factory methods. All factory methods from UnfoldingTool are available.

Properties

childToolUsageNotes

open val childToolUsageNotes: String?

Detail that is progressively disclosed: hidden until the LLM invokes this tool, then appended verbatim to the unfolded message returned by call (after the "Tools now available: …" preamble).

abstract val definition: Tool.Definition

Tool definition for LLM

open val exclusive: Boolean

When true, expanding this tool removes ALL other tools from the LLM's tool set — the LLM will only see the inner tools until the interaction ends. Use this for tools where the LLM consistently picks the wrong sibling tool instead of using the inner tools (e.g., personality changes).

abstract override val innerTools: List<Tool>

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

open val metadata: Tool.Metadata

Optional metadata

open val ~~removeOnInvoke~~: Boolean

Whether to remove this tool after invocation.

Functions

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

Execute the tool with JSON input.

open fun call(input: String, context: ToolCallContext): Tool.Result

Execute the tool with JSON input and out-of-band context.

open override fun innerTools(process: AgentProcess): List<Tool>

Returns the fixed innerTools regardless of process context.

inline fun <T : Any> Tool.requireType(message: String? = null): Tool

Wrap this tool to require a value of type T before execution (reified).

fun <T : Any> Tool.requireType(type: Class<T>, messageProvider: (String) -> String? = { null }): Tool

Wrap this tool to require a value of type T before execution.

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.

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

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

fun Tool.withAwaiting(decider: AwaitDecider): Tool

Wrap this tool to conditionally await before execution.

withConfirmation

fun Tool.withConfirmation(messageProvider: (String) -> String): Tool

fun Tool.withConfirmation(message: String): Tool

Wrap this tool to always require confirmation before execution.

withDefinitionMetadata

open fun withDefinitionMetadata(entries: Map<String, Any>): Tool

Create a new tool with additional definition metadata entries merged in. Existing keys are overwritten by the new values.

open fun withDefinitionMetadata(key: String, value: Any): Tool

Create a new tool with a single definition metadata entry added.

withDescription

open fun withDescription(newDescription: String): Tool

Create a new tool with a different description. Useful for providing context-specific descriptions while keeping the same functionality.

withEventPublication

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

Extension function to wrap a Tool with event publication.

open fun withName(newName: String): Tool

Create a new tool with a different name. Useful for namespacing tools when combining multiple tool sources.

open fun withNote(note: String): Tool

Create a new tool with an additional note appended to the description. Useful for adding context-specific hints to an existing tool.

open fun withToolObject(toolObject: Any): UnfoldingTool

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

open fun withTools(vararg tools: Tool): UnfoldingTool

Create a new UnfoldingTool with additional tools added.