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.

Types

Companion

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?

Optional usage notes to guide the LLM on when to invoke the child tools.

definition

abstract val definition: Tool.Definition

Tool definition for LLM

includeContextTool

open val includeContextTool: Boolean

Whether to include a context tool when this tool is unfolded.

innerTools

abstract 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.

metadata

open val metadata: Tool.Metadata

Optional metadata

removeOnInvoke

open val removeOnInvoke: Boolean

Whether to remove this tool after invocation.

Functions

call

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

Execute the tool with JSON input.

innerTools

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

Returns the fixed innerTools regardless of process context.

requireType

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.

selectTools

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.

unwrapAs

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

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

withAwaiting

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.

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.

withName

open fun withName(newName: String): Tool

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

withNote

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.

withToolObject

open fun withToolObject(toolObject: Any): UnfoldingTool

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

withTools

open fun withTools(vararg tools: Tool): UnfoldingTool

Create a new UnfoldingTool with additional tools added.