/microsoft-foundry

Tool — Tool Search (preview) (type: toolbox_search_preview)

For 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.

Tool Search is a connectionless directive — it's declared under a tools: block (like web_search); no project connection required. It is not a standalone toolbox: pair it with the tools it should index (see Behavior and the Multi-tool rule).

🚦 Before creating a toolbox/connection either way, read create-hosted.md → Toolbox creation boundary.

Toolbox shape

{ "type": "toolbox_search_preview" }

A. Imperative CLI

Steps 1–3 of toolbox.md § The flow. Tool Search needs no connection, so it goes under a tools: block. Write the toolbox spec to a file — azd ai toolbox create --from-file takes a path (stdin - is not supported). Because toolbox_search_preview counts as the one allowed unnamed tool, every other tool in the same spec must carry a name / server_label, or the create fails with 400 invalid_payload: Multiple tools without identifiers found.

# 0. Install the CLI extension (once)
azd extension install azure.ai.toolboxes

# Write the toolbox spec to a file — Tool Search directive + the tools it indexes
cat > ts.yaml <<'EOF'
description: agent-tools with Tool Search
tools:
  - type: toolbox_search_preview       # the one allowed unnamed tool
  - type: web_search
    name: web_search                   # MUST be named once toolbox_search_preview is present
connections:
  - name: analytics-mcp                # any MCP connections to index (RemoteTool)
EOF

Create a new toolbox (first version auto-promoted):

azd ai toolbox create agent-tools --from-file ts.yaml --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

Add to an existing toolbox: like other connectionless built-ins, the current azd CLI does not support adding toolbox_search_preview to an existing toolbox via azd ai toolbox connection add — recreate the toolbox (azd ai toolbox create) with the full tool set.

--from-file entry:

tools:
  - type: toolbox_search_preview       # connectionless directive; unnamed (counts as the one unnamed tool)

B. Declarative azure.yaml

Declare the toolbox as a host: azure.ai.toolbox service in azure.yaml; azd deploy upserts it (and auto-promotes the new version). Needs only an existing Foundry project (via FOUNDRY_PROJECT_ENDPOINT + AZURE_SUBSCRIPTION_ID in the azd env) — no azd provision, no infra: block.

name: my-agent-project
services:
  agent-tools:
    host: azure.ai.toolbox
    tools:
      - type: toolbox_search_preview   # the one unnamed tool
      - type: web_search
        name: web_search               # named — required alongside toolbox_search_preview
      - type: mcp
        server_label: analytics        # server_label acts as its identifier
        project_connection_id: analytics-mcp

  # A hosted agent in the same project consumes the toolbox by name
  my-agent:
    host: azure.ai.agent
    uses:
      - agent-tools          # depend on the toolbox service
    environmentVariables:
      - name: TOOLBOX_NAME
        value: agent-tools    # agent resolves the MCP endpoint at runtime

azd deploy agent-tools

The agent references the toolbox by name (TOOLBOX_NAME), so the MCP endpoint resolves at runtime — no endpoint string is hard-coded. See use-toolbox-in-hosted-agent.md.

Behavior

• toolbox_search_preview is a configuration directive — it doesn't appear in tools/list itself, but it counts as the toolbox's one allowed unnamed tool. If you pair it with any other unnamed tool (e.g. a bare web_search), the create fails with 400 invalid_payload: Multiple tools without identifiers found — give the other tools a name / server_label.

• 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).

• Pin specific tools or add search-only keywords via tool_configs.{tool_name}:

  {
    "type": "mcp",
    "server_label": "analytics",
    "server_url": "https://db-mcp.internal/sse",
    "tool_configs": {
      "execute_query": { "pin": true, "additional_search_text": "SQL analytics reporting dashboard" },
      "*":             { "additional_search_text": "data warehouse queries" }
    }
  }

  Use "*" as the key to apply settings to all tools in that entry.

• additional_search_text is used only for search ranking — it's never exposed to the model in the tool schema.

• Tool descriptions drive match quality: every MCP tool should have a clear description, or tool_search won't find it.

• 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.

Verify & deploy

After creating the toolbox either way, verify its MCP endpoint end-to-end — with Tool Search enabled, tools/list returns only tool_search + call_tool (the indexed tools are hidden until a tool_search call surfaces them). See test-endpoint.md.

References

For full fields, pinning recipes, the verify-with-tool_search flow, and best practices, see Tool Search tool documentation.

• agent-tools.md — tool index
• toolbox.md § Enable Tool Search