1# Tool — Tool Search (preview)
2 
3For toolboxes containing many tools, replace the full tool list passed to the model with two meta-tools — `tool_search` (natural-language discovery, returns matching tools per query) and `call_tool` (invoke any discovered tool by name) — so context cost stays flat regardless of toolbox size.
4 
5## Toolbox shape
6 
7```json
8{ "type": "toolbox_search_preview" }
9```
10 
11## Behavior
12 
13- `toolbox_search_preview` is a **configuration directive** — it doesn't appear in `tools/list` itself and doesn't count toward the unnamed-tool-per-type limit.
14- All other toolbox tools are **hidden** from the initial `tools/list` and are returned only by `tool_search` calls (or by per-user auto-pinning of hot tools).
15- Pin specific tools or add search-only keywords via `tool_configs.{tool_name}`:
16 
17  ```json
18  {
19    "type": "mcp",
20    "server_label": "analytics",
21    "server_url": "https://db-mcp.internal/sse",
22    "tool_configs": {
23      "execute_query": { "pin": true, "additional_search_text": "SQL analytics reporting dashboard" },
24      "*":             { "additional_search_text": "data warehouse queries" }
25    }
26  }
27  ```
28 
29  Use `"*"` as the key to apply settings to all tools in that entry.
30- `additional_search_text` is used only for search ranking — it's never exposed to the model in the tool schema.
31- Tool **descriptions drive match quality**: every MCP tool should have a clear `description`, or `tool_search` won't find it.
32- Recommendation: add an instruction in the system prompt telling the model to call `tool_search` when a needed capability isn't in its current tool list.
33 
34## References
35 
36For full fields, pinning recipes, the verify-with-`tool_search` flow, and best practices, see [Tool Search tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/tool-search).
37 
38- [agent-tools.md](agent-tools.md) — tool index
39- [use-toolbox-in-hosted-agent.md § Recommendation: enable Tool Search](use-toolbox-in-hosted-agent.md#-recommendation-enable-tool-search)
40