Embabel Agent Documentation/com.embabel.agent.api.tool.progressive/UnfoldingTool

UnfoldingTool

interface UnfoldingTool : ProgressiveTool

A ProgressiveTool with a fixed set of inner tools that are revealed when invoked, regardless of the agent process context.

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

Context Preservation

When an UnfoldingTool is expanded, a context tool can be created that preserves the parent's description and optional usage notes. This solves the problem where child tools would lose context about the parent's purpose.

The childToolUsageNotes field provides additional guidance on how to use the child tools, included only once in the context tool rather than duplicated in each child tool's description.

Example:

val spotifyTool = UnfoldingTool.of(
    name = "spotify_search",
    description = "Search Spotify for music data including artists, albums, and tracks.",
    innerTools = listOf(vectorSearchTool, textSearchTool, regexSearchTool),
    childToolUsageNotes = "Try vector search first for semantic queries like 'upbeat jazz'. " +
        "Use text search for exact artist or album names. " +
        "Use regex search for pattern matching on metadata."
)

See also

ProgressiveTool

for context-dependent tool revelation

Inheritors

Types

object Companion : UnfoldingTool.Factory

open class Factory

Factory methods for creating UnfoldingTool instances. This is an open class so that subinterface companions can extend it.

Properties

childToolUsageNotes

open val childToolUsageNotes: String?

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

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.

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.

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

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.