https://github.com/spring-ai-community/spring-ai-tool-search-tool
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.
https://github.com/spring-ai-community/spring-ai-tool-search-tool
agentic-ai spring-ai tool-calling
Last synced: 3 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/spring-ai-community/spring-ai-tool-search-tool
- Owner: spring-ai-community
- License: apache-2.0
- Created: 2025-12-10T04:16:21.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T12:34:07.000Z (5 months ago)
- Last Synced: 2026-01-27T01:18:21.877Z (5 months ago)
- Topics: agentic-ai, spring-ai, tool-calling
- Language: Java
- Homepage: https://spring.io/blog/2025/12/11/spring-ai-tool-search-tools-tzolov
- Size: 420 KB
- Stars: 37
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Tool Search Tool for Spring AI [](https://github.com/spring-ai-community/spring-ai-tool-search-tool/actions/workflows/publish-snapshot.yml) [](https://central.sonatype.com/artifact/org.springaicommunity/tool-search-tool) [](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
> _**NOTE:** This is Spring AI 2.x / Boot 4 compatibible version._
> _For Spring AI 1.1.x / Boot 3 support switch to: [Tool Search Tool - v1.0.x](https://github.com/spring-ai-community/spring-ai-tool-search-tool/tree/1.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. **Itroduction blog:** [Smart Tool Selection: Achieving 34-64% Token Savings with Spring AI's Dynamic Tool Discovery](https://spring.io/blog/2025/12/11/spring-ai-tool-search-tools-tzolov)
### 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](https://www.anthropic.com/engineering/advanced-tool-use)** 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:
```xml
org.springaicommunity
tool-search-tool
2.0.1
org.springaicommunity
tool-searcher-lucene
2.0.1
```
For snapshot versions add the snapshot repository to your `pom.xml`:
```xml
central-snapshots
https://central.sonatype.com/repository/maven-snapshots/
true
```
### 2. Configure the Advisor
```java
@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](tool-searchers/README.md) 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](tool-search-tool/README.md) for detailed documentation.
## Examples
### Tool Search Tool Demo (Recommended)
LLM actively discovers tools on-demand:
```bash
cd examples/tool-search-tool-demo
mvn spring-boot:run
```
See [example README](examples/tool-search-tool-demo/README.md).
### Pre-Select Tool Demo (Alternative)
Pre-selects tools based on conversation context:
```bash
cd examples/pre-select-tool-demo
mvn spring-boot:run
```
See [example README](examples/pre-select-tool-demo/README.md).
## Building
```bash
mvn clean install
```
## Requirements
- Java 17+
- Spring AI 2.0.0-M2+
- 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](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)
- [Anthropic's Advanced Tool Use Blog](https://www.anthropic.com/engineering/advanced-tool-use)
- [Spring AI Tool Calling](https://docs.spring.io/spring-ai/reference/api/tools.html)
- [Spring AI Recursive Advisors](https://docs.spring.io/spring-ai/reference/api/advisors-recursive.html)
## License
Apache License 2.0 - See [LICENSE.txt](LICENSE.txt)