All Implemented Interfaces:

com.embabel.agent.api.tool.Tool , com.embabel.agent.api.tool.ToolInfo , com.embabel.agent.api.tool.agentic.AgenticTool , com.embabel.agent.api.tool.agentic.ToolChaining
```
public final class PlaybookTool
 implements AgenticTool<PlaybookTool>
                    
```
A tool with conditional tool unlocking that uses an LLM to orchestrate sub-tools.
Unlike com.embabel.agent.api.tool.agentic.simple.SimpleAgenticTool which makes all tools available immediately, a PlaybookTool allows tools to be progressively unlocked based on conditions such as:
- Prerequisites: unlock after other tools have been called
- Artifacts: unlock when certain artifact types are produced
- Blackboard: unlock based on process state
- Custom predicates: unlock based on arbitrary conditions
This provides more predictable LLM behavior by guiding it through a structured sequence of available tools.
```
// Kotlin curried syntax
PlaybookTool("researcher", "Research and analyze topics")
    .withTools(searchTool, fetchTool)           // always available
    .withTool(analyzeTool)(searchTool)          // unlocks after search
    .withTool(summarizeTool)(analyzeTool)       // unlocks after analyze

// Java fluent syntax
new PlaybookTool("researcher", "Research and analyze topics")
    .withTools(searchTool, fetchTool)
    .withTool(analyzeTool).unlockedBy(searchTool)
    .withTool(summarizeTool).unlockedBy(analyzeTool);
```

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`public class`	`PlaybookTool.Companion`

Field Summary

Fields
Modifier and Type	Field	Description
`private final Integer`	`unlockedToolCount`
`private final Integer`	`lockedToolCount`
`private final Tool.Definition`	`definition`
`private final Tool.Metadata`	`metadata`
`private final LlmOptions`	`llm`
`private final AgenticSystemPromptCreator`	`systemPromptCreator`
`private final Integer`	`maxIterations`
`public final static PlaybookTool.Companion`	`Companion`

Constructor Summary

Constructors
Constructor	Description
`PlaybookTool(String name, String description)`	Create a playbook tool with the given name and description.

Enum Constant Summary

Enum Constants
Enum Constant	Description

Method Summary

Modifier and Type	Method	Description
`final Integer`	`getUnlockedToolCount()`
`final Integer`	`getLockedToolCount()`
`Tool.Definition`	`getDefinition()`
`Tool.Metadata`	`getMetadata()`
`LlmOptions`	`getLlm()`
`final AgenticSystemPromptCreator`	`getSystemPromptCreator()`
`Integer`	`getMaxIterations()`
`Tool.Result`	`call(String input)`	Execute the tool with JSON input.
`final PlaybookTool`	`withTools(Tool tools)`	Add tools that are always available (no unlock conditions).
`final ToolRegistration`	`withTool(Tool tool)`	Begin registration of a tool with unlock conditions.
`PlaybookTool`	`withLlm(LlmOptions llm)`	Create a copy with different LLM options.
`PlaybookTool`	`withSystemPrompt(AgenticSystemPromptCreator creator)`	Create a copy with a dynamic system prompt creator.
`PlaybookTool`	`withMaxIterations(Integer maxIterations)`	Create a copy with a different max iterations limit.
`PlaybookTool`	`withParameter(Tool.Parameter parameter)`	Create a copy with an additional parameter in the definition.
`PlaybookTool`	`withToolObject(Object toolObject)`	Create a copy with tools extracted from an object with @LlmTool methods.
`<T extends Any> PlaybookTool`	`withToolChainingFrom(Class<T> type, DomainToolPredicate<T> predicate)`	Register a domain class with a predicate to control when its @LlmTool methods are exposed.
`final <T extends Any> PlaybookTool`	`withToolChainingFrom(Function2<T, AgentProcess, Boolean> predicate)`	Register a class with a predicate.
`final <T extends Any> PlaybookTool`	`withToolChainingFrom()`	Register a class that can contribute @LlmTool methods when a single instance is retrieved.
`PlaybookTool`	`withToolChainingFromAny()`	Enable auto-discovery of chained tools from any returned artifact.

Methods inherited from class com.embabel.agent.api.tool.agentic.AgenticTool
withSystemPrompt
Methods inherited from class com.embabel.agent.api.tool.agentic.ToolChaining
withToolChainingFrom
Methods inherited from class com.embabel.agent.api.tool.Tool
withDescription, withName, withNote
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PlaybookTool
```
PlaybookTool(String name, String description)
```
    Create a playbook tool with the given name and description.
- Method Detail
  - getUnlockedToolCount
```
 final Integer getUnlockedToolCount()
```
  - getLockedToolCount
```
 final Integer getLockedToolCount()
```
  - getDefinition
```
 Tool.Definition getDefinition()
```
  - getMetadata
```
 Tool.Metadata getMetadata()
```
  - getLlm
```
 LlmOptions getLlm()
```
  - getSystemPromptCreator
```
 final AgenticSystemPromptCreator getSystemPromptCreator()
```
  - getMaxIterations
```
 Integer getMaxIterations()
```
  - call
```
 Tool.Result call(String input)
```
    Execute the tool with JSON input.
    
    Parameters:
    
    input - JSON string matching inputSchema
    
    Returns:
    
    Result to send back to LLM
  - withTools
```
 final PlaybookTool withTools(Tool tools)
```
    Add tools that are always available (no unlock conditions).
  - withTool
```
 final ToolRegistration withTool(Tool tool)
```
    Begin registration of a tool with unlock conditions. Returns a ToolRegistration that can be used with curried syntax or fluent API.
    // Kotlin curried .withTool(analyzeTool)(searchTool) // Java fluent .withTool(analyzeTool).unlockedBy(searchTool)
  - withLlm
```
 PlaybookTool withLlm(LlmOptions llm)
```
    Create a copy with different LLM options.
  - withSystemPrompt
```
 PlaybookTool withSystemPrompt(AgenticSystemPromptCreator creator)
```
    Create a copy with a dynamic system prompt creator. The creator receives the execution context and input string.
  - withMaxIterations
```
 PlaybookTool withMaxIterations(Integer maxIterations)
```
    Create a copy with a different max iterations limit.
  - withParameter
```
 PlaybookTool withParameter(Tool.Parameter parameter)
```
    Create a copy with an additional parameter in the definition.
  - withToolObject
```
 PlaybookTool withToolObject(Object toolObject)
```
    Create a copy with tools extracted from an object with @LlmTool methods. If the object has no @LlmTool methods, returns this unchanged.
  - withToolChainingFrom
```
 <T extends Any> PlaybookTool withToolChainingFrom(Class<T> type, DomainToolPredicate<T> predicate)
```
    Register a domain class with a predicate to control when its @LlmTool methods are exposed.
    When a single artifact of the specified type is returned by any tool and passes the predicate, any @LlmTool annotated methods on that instance become available as tools.
    
    Parameters:
    
    type - The domain class that may contribute tools
    
    predicate - Predicate to filter which instances contribute tools
  - withToolChainingFrom
```
 final <T extends Any> PlaybookTool withToolChainingFrom(Function2<T, AgentProcess, Boolean> predicate)
```
    Register a class with a predicate. Kotlin-friendly version using reified type parameter.
  - withToolChainingFrom
```
 final <T extends Any> PlaybookTool withToolChainingFrom()
```
    Register a class that can contribute @LlmTool methods when a single instance is retrieved. Kotlin-friendly version using reified type parameter.
    Example:
    PlaybookTool("userManager", "Manage users") .withTools(searchUserTool, getUserTool) .withToolChainingFrom<User>() // User methods become available when a single User is retrieved
  - withToolChainingFromAny
```
 PlaybookTool withToolChainingFromAny()
```
    Enable auto-discovery of chained tools from any returned artifact.
    When enabled, any artifact with @LlmTool methods will automatically have its tools exposed, replacing ALL previous bindings.

Class PlaybookTool

Nested Class Summary

Field Summary

Constructor Summary

Enum Constant Summary

Method Summary

Methods inherited from class com.embabel.agent.api.tool.agentic.AgenticTool

Methods inherited from class com.embabel.agent.api.tool.agentic.ToolChaining

Methods inherited from class com.embabel.agent.api.tool.Tool

Methods inherited from class java.lang.Object

Constructor Detail

PlaybookTool

Method Detail

getUnlockedToolCount

getLockedToolCount

getDefinition

getMetadata

getLlm

getSystemPromptCreator

getMaxIterations

call

withTools

withTool

withLlm

withSystemPrompt

withMaxIterations

withParameter

withToolObject

withToolChainingFrom

withToolChainingFrom

withToolChainingFrom

withToolChainingFromAny