1  ---
  2  title: "SearchableToolset"
  3  id: searchabletoolset
  4  slug: "/searchabletoolset"
  5  description: "Enable agents to dynamically discover tools from large catalogs using keyword-based search."
  6  ---
  7  
  8  # SearchableToolset
  9  
 10  Enable agents to dynamically discover tools from large catalogs using keyword-based search.
 11  
 12  <div className="key-value-table">
 13  
 14  |  |  |
 15  | --- | --- |
 16  | **Mandatory init variables** | `catalog`: A list of Tools and/or Toolsets, or a single Toolset |
 17  | **API reference**            | [SearchableToolset](/reference/tools-api#searchabletoolset) |
 18  | **GitHub link**              | https://github.com/deepset-ai/haystack/blob/main/haystack/tools/searchable_toolset.py |
 19  
 20  </div>
 21  
 22  ## Overview
 23  
 24  `SearchableToolset` is designed for working with large tool catalogs.
 25  Instead of exposing all tools at once, which can overwhelm the LLM context, it provides a single `search_tools` bootstrap tool.
 26  The agent uses this tool to find and load specific tools from the catalog using BM25 keyword search.
 27  
 28  Once the agent calls `search_tools`, the matching tools become immediately available and the agent can invoke them in
 29  subsequent iterations.
 30  
 31  ### Modes of operation
 32  
 33  `SearchableToolset` operates in one of two modes depending on catalog size:
 34  
 35  - **Search mode** (default for large catalogs): The agent starts with only the `search_tools` bootstrap tool and discovers other tools on demand. This is activated when the catalog size meets or exceeds `search_threshold`.
 36  - **Passthrough mode** (small catalogs): All tools are exposed directly, with no discovery step needed. This is activated automatically when the catalog has fewer tools than `search_threshold`.
 37  
 38  ### Parameters
 39  
 40  - `catalog` (required): The source of tools — a list of `Tool` and/or `Toolset` instances, or a single `Toolset`. This includes [MCPTool](mcptool.mdx) and [MCPToolset](mcptoolset.mdx) instances.
 41  - `top_k` (optional): The default number of tools returned by each `search_tools` call. Default is `3`.
 42  - `search_threshold` (optional): Minimum catalog size to activate search mode. Catalogs smaller than this value use passthrough mode instead. Default is `8`.
 43  
 44  :::info
 45  `SearchableToolset` does not support adding new tools after initialization or merging with other toolsets. Use `catalog` to provide all tools upfront.
 46  :::
 47  
 48  ## Usage
 49  
 50  ### Basic usage with an Agent
 51  
 52  ```python
 53  from typing import Annotated
 54  from haystack.components.agents import Agent
 55  from haystack.components.generators.chat import OpenAIChatGenerator
 56  from haystack.dataclasses import ChatMessage
 57  from haystack.tools import create_tool_from_function, SearchableToolset
 58  
 59  
 60  def get_weather(city: Annotated[str, "The city to get the weather for"]) -> str:
 61      """Get current weather for a city."""
 62      return f"Sunny, 22°C in {city}"
 63  
 64  
 65  def search_web(query: Annotated[str, "The search query"]) -> str:
 66      """Search the web for information."""
 67      return f"Results for: {query}"
 68  
 69  
 70  # Build a catalog from tools
 71  catalog = [
 72      create_tool_from_function(get_weather),
 73      create_tool_from_function(search_web),
 74      # ... many more tools
 75  ]
 76  
 77  toolset = SearchableToolset(catalog=catalog)
 78  
 79  agent = Agent(
 80      chat_generator=OpenAIChatGenerator(),
 81      tools=toolset,
 82  )
 83  
 84  # The agent initially sees only `search_tools`. It will call it to find relevant tools,
 85  # then use the discovered tools to answer the question.
 86  result = agent.run(messages=[ChatMessage.from_user("What's the weather in Milan?")])
 87  print(result["messages"][-1].text)
 88  ```
 89  
 90  ### Customizing the bootstrap tool
 91  
 92  You can customize the name, description, and parameter descriptions of the `search_tools` bootstrap tool:
 93  
 94  - `search_tool_name`: Custom name for the bootstrap tool. Default is `"search_tools"`.
 95  - `search_tool_description`: Custom description for the bootstrap tool.
 96  - `search_tool_parameters_description`: Custom descriptions for the bootstrap tool's parameters. Keys must be a subset of `{"tool_keywords", "k"}`.
 97  
 98  ```python
 99  toolset = SearchableToolset(
100      catalog=catalog,
101      search_tool_name="find_tools",
102      search_tool_description="Search for tools in the catalog by keyword.",
103      search_tool_parameters_description={
104          "tool_keywords": "Keywords to find tools, e.g. 'email send'",
105          "k": "Max number of tools to return",
106      },
107  )
108  ```
109  
110  ### Reusing the toolset across multiple agent runs
111  
112  When reusing the same `SearchableToolset` instance across multiple agent runs, you can call `clear()` to reset any tools discovered in the previous run:
113  
114  ```python
115  agent = Agent(
116      chat_generator=OpenAIChatGenerator(),
117      tools=toolset,
118  )
119  
120  result1 = agent.run(messages=[ChatMessage.from_user("What's the weather in Milan?")])
121  
122  # Reset discovered tools before the next run
123  toolset.clear()
124  
125  result2 = agent.run(messages=[ChatMessage.from_user("Search for news about AI.")])
126  ```