Skip to main content
When a toolbox contains many tools, passing all tool definitions to the model on every turn creates three compounding problems: token costs grow with every tool added to the context, the context window fills with definitions the current task doesn’t need, and the model picks the wrong tools from an overcrowded list. Tool search solves this problem by replacing the full tool list with two focused meta-tools, so cost stays flat regardless of toolbox size. When you enable tool search, the model gets two built-in meta-tools: tool_search, which it calls with a natural-language description of the capability it needs, and call_tool, which it uses to invoke any discovered tool by name. Foundry evaluates tool_search queries against the full set of tools in the toolbox and returns only the ones that match, so the active context stays focused and relevant. For request-scoped discovery of deferred tool definitions, see Use tool search with the Azure OpenAI Responses API. Use tool search when:
  • Your toolbox has more than 10–15 tools and you want to avoid context bloat.
  • Different agent tasks need different subsets of tools, and you want the model to pick the right subset dynamically.

​
Prerequisites

​
How tool search works

When you include {"type": "toolbox_search"} in a toolbox, the initial tools/list response hides all tools in the toolbox. Instead, Foundry adds two meta-tools:
  • tool_search — the model calls this tool with a natural-language description of the capability it needs. Foundry evaluates the query and returns the matching tool definitions.
  • call_tool — the model uses this tool to invoke any discovered tool by name.
The model doesn’t browse a full tool list. It describes intent, discovers the right tools, and calls them.

​
Search mechanism

Tool search uses BM25 (Best Matching 25), a probabilistic ranking algorithm that scores tools based on how well their metadata matches the query. BM25 considers term frequency, inverse document frequency, and document length normalization to rank results. When the model calls tool_search, Foundry indexes each tool’s name, description, and parameter information, then returns the top-scoring matches for the query.

​
Parameters

The tool_search function accepts the following parameters: The model can call tool_search as many times as needed during a single turn. Each call returns only the tools that match the query, so the active context stays focused on what’s relevant to the current step. Tools returned by tool_search remain callable for the rest of the turn without repeated searching.
The toolbox_search entry is a configuration directive that activates tool search. It doesn’t appear in tools/list itself and doesn’t count toward the unnamed-tool-per-type limit.
Add {"type": "toolbox_search"} to your toolbox version’s tools list. All other tools in the toolbox are available through tool search - the initial tool list the model sees doesn’t expose them.

​
Verify tool search is active

Use the version-specific endpoint to confirm that tool_search, call_tool, and any pinned tools appear in tools/list. Ordinary unpinned toolbox tools must remain hidden from the initial listing.

​
Fine-tune tool discovery

Tool search works without extra configuration. For predictable usage patterns, tune how specific tools are surfaced and indexed. Foundry Toolkit supports enabling tool search. To configure pinned tools or extra search keywords, select the Python, .NET, JavaScript, or REST API tab in this section.

​
Pin critical tools

Use pin to make a specific tool always appear in tools/list alongside tool_search and call_tool. Pinned tools are callable immediately without a search round-trip. To pin every tool in an MCP server or built-in tool entry, use "*" as the key. To pin every tool in an entry, use "*" as the key:

​
Add search keywords

If a tool’s MCP description doesn’t match the vocabulary users naturally use, add keywords by using additional_search_text. The extra text is used only for search ranking - it’s never exposed to the model in the tool schema.

​
Auto-pinning

Foundry automatically tracks which tools each user calls most frequently and surfaces them directly in tools/list—no configuration required. After a short warmup period, frequently used tools appear without a search round-trip. The hot set is per-user and updates as usage patterns shift; stale entries age out automatically. Auto-pinning composes with explicit pin and additional_search_text configuration. Pin the critical tools you know about upfront, add keywords for tools with ambiguous names, and let auto-pinning handle the long tail as usage patterns emerge.

​
Configuration reference

Include {"type": "toolbox_search"} in your toolbox’s tools list to enable tool search. All other configuration fields are optional.

​
tool_configs (per-tool)

Set tool_configs on an individual MCP tool entry to control how specific tools behave within the search context. Use an exact tool name as the key to configure a specific tool, or "*" to apply the configuration to all tools in that entry.

​
Considerations

  • All toolbox tools are hidden from the initial listing. When toolbox_search is in a toolbox, no other toolbox tools appear in tools/list. The model discovers them only through tool_search. Tools added directly to an agent outside the toolbox are unaffected and remain visible.
  • Tool descriptions drive match quality. Foundry uses tool names and descriptions to evaluate search queries. A tool without a description, or with a vague one, is unlikely to be returned even for relevant queries. Write descriptions that describe what the tool does and the kinds of tasks it handles.
  • tool_search doesn’t count toward tool limits. The platform injects it and it doesn’t consume the unnamed-tool-per-type slot.
  • Multiple searches per turn are supported. The model can call tool_search more than once in a single turn if different steps need different capabilities.
  • Returned tools persist for the turn. Once a tool is returned by tool_search, the model can call it multiple times without re-searching.
  • Pinned tools always appear in tools/list. Tools with "pin": True in tool_configs appear alongside tool_search and call_tool on every turn, regardless of search queries.
  • Auto-pinning surfaces frequently used tools automatically. Foundry tracks per-user tool call frequency and promotes the most-called tools to tools/list after a short warmup period. The hot set is per-user and updates as usage patterns shift.
  • OAuth consent might be required. If any tool in the toolbox connects to an OAuth-based MCP server, the first call returns a CONSENT_REQUIRED error (code -32006) with a consent URL in the response. Open that URL in a browser, complete the OAuth flow, then retry. Subsequent calls succeed without re-prompting. See Troubleshoot toolbox errors for handling this error.

​
Best practices

  • Add a description to every tool. Tool search uses descriptions to match tools to queries. A missing or vague description causes poor discovery.
  • Use tool search for large toolboxes. This configuration is most effective when you have 10 or more tools.
  • Use tool search together with toolbox versioning. Test your configuration on a version-specific endpoint before promoting it to default.
  • Mention tool search in the system prompt. Guide the model to call tool_search before concluding that a capability is unavailable. For example: “If you need a tool that isn’t in your current list, call tool_search with a description of what you need before responding that you can’t help.”
  • Pin always-needed tools. Use "pin": True in tool_configs for tools called on nearly every turn to skip the search round-trip.
  • Use additional_search_text when descriptions are ambiguous. If your team uses different vocabulary than the MCP server’s tool descriptions, add keywords to improve search precision without modifying the server.

​
Troubleshoot

​
Related content