Spring AI Tool Search Tool

Dynamic tool discovery and selection for Spring AI, enabling LLMs to work efficiently with large tool libraries

GitHub • Maven

Overview

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.

Tool Search Tool implements Anthropic’s 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 (80-90%) while maintaining access to thousands of tools.

Version: 1.0.0-SNAPSHOT Maven snapshot artifacts are available from Maven Central Snapshots

Key Benefits

Token Efficiency

Reduced context windows with 80-90% token savings

Better Accuracy

Models select the right tool when focused on fewer options

Portable

Works with any LLM supported by Spring AI

Observable

Leverages Spring AI’s advisor chain for logging and monitoring

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

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)

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

Quick Start

1. Add Dependencies

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>

Then add the dependencies:

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

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

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();
    };
}

Examples

Tool Search Tool Demo (Recommended)

LLM actively discovers tools on-demand:

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

Pre-Select Tool Demo (Alternative)

Pre-selects tools based on conversation context:

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

Requirements

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

Resources

GitHub Repository

View source code and contribute

Anthropic's Tool Search Tool

Original pattern documentation

Spring AI Tool Calling

Spring AI’s tool calling docs

Spring AI Advisors

Recursive advisors documentation

License

Spring AI Tool Search Tool is Open Source software released under the Apache 2.0 license.