Tool Search Tool for Spring AI

📖 Documentation

NOTE: This is Spring AI 2.x / Boot 4 compatible version. For Spring AI 1.1.x / Boot 3 support switch to: Tool Search Tool - v1.0.x

Dynamic tool discovery and selection for Spring AI, enabling LLMs to work efficiently with large tool libraries by discovering tools on-demand instead of loading all definitions upfront. Introduction blog: Smart Tool Selection: Achieving 34-64% Token Savings with Spring AI's Dynamic Tool Discovery

The Problem

As AI agents connect to more services—Slack, GitHub, Jira, MCP servers—tool libraries grow rapidly. A typical multi-server setup can easily have 50+ tools consuming 55,000+ tokens before any conversation starts. Tool selection accuracy also degrades when models face 30+ similarly-named tools.

The Solution

This project implements the Tool Search Tool pattern for Spring AI:

• Model receives only a search tool initially (minimal tokens)
• When capabilities are needed, model searches for relevant tools
• Matching tool definitions are dynamically expanded into context
• Model invokes discovered tools to complete the task

Result: Significant token savings while maintaining access to thousands of tools.

Project Structure

spring-ai-tool-search-tool/
├── tool-search-tool/           # Core advisor implementation
├── tool-searchers/             # Pluggable search strategies
│   ├── tool-searcher-vectorstore/   # Semantic search (embeddings)
│   ├── tool-searcher-lucene/        # Keyword search (full-text)
│   └── tool-searcher-regex/         # Pattern matching
├── tool-search-tool-bom/       # Bill of Materials
└── examples/
    ├── tool-search-tool-demo/  # Recommended approach
    └── pre-select-tool-demo/   # Alternative approach

Quick Start

1. Add Dependencies

Then add the dependencies:

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>tool-search-tool</artifactId>
    <version>2.1.0</version>
</dependency>

<!-- Choose a search strategy -->
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>tool-searcher-lucene</artifactId>
    <version>2.1.0</version>
</dependency>

For snapshot versions add the snapshot repository to your pom.xml:

<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

2. Configure the Advisor

@Bean
ToolSearcher toolSearcher() {
    return new LuceneToolSearcher(0.4f);
}

@Bean
CommandLineRunner demo(ChatClient.Builder builder, ToolSearcher toolSearcher) {
    return args -> {
        var advisor = ToolSearchToolCallAdvisor.builder()
            .toolSearcher(toolSearcher)
            .build();

        ChatClient chatClient = builder
            .defaultTools(new MyTools())  // 100s of tools - NOT sent to LLM initially
            .defaultAdvisors(advisor)
            .build();

        String answer = chatClient
            .prompt("What's the weather in Amsterdam?")
            .call()
            .content();
    };
}

Search Strategies

Strategy	Module	Best For
Semantic	tool-searcher-vectorstore	Natural language queries, fuzzy matching
Keyword	tool-searcher-lucene	Exact term matching, known tool names
Regex	tool-searcher-regex	Tool name patterns (get_*, *_api)

See Tool Searchers README for detailed documentation.

How It Works

1. Indexing: Tools are indexed in the ToolSearcher (not sent to LLM)
2. Initial Request: Only toolSearchTool definition is sent to LLM
3. Discovery: LLM calls toolSearchTool(query="weather") to find relevant tools
4. Expansion: Discovered tools are added to next request
5. Execution: LLM calls discovered tools to complete the task
6. Response: Final answer generated

See Tool Search Tool README for detailed documentation.

Examples

Tool Search Tool Demo (Recommended)

LLM actively discovers tools on-demand:

cd examples/tool-search-tool-demo
mvn spring-boot:run

See example README.

Pre-Select Tool Demo (Alternative)

Pre-selects tools based on conversation context:

cd examples/pre-select-tool-demo
mvn spring-boot:run

See example README.

Building

mvn clean install

Requirements

• Java 17+
• Spring AI 2.0.0-M4+
• Maven 3.6+

Key Benefits

• Token efficiency - Reduced context windows (80-90% savings)
• Better accuracy - Models select the right tool when focused on fewer options
• Portable - Works with any LLM supported by Spring AI
• Flexible - Swap search strategies based on your use case
• Observable - Leverages Spring AI's advisor chain for logging and monitoring

Related Resources

• Anthropic's Tool Search Tool
• Anthropic's Advanced Tool Use Blog
• Spring AI Tool Calling
• Spring AI Recursive Advisors

License

Apache License 2.0 - See LICENSE.txt