Microsoft Foundry Toolbox and Tool Search: One Endpoint for Agent Tool Governance

In the video, I use a customer-meeting-preparation agent to demonstrate Microsoft Foundry Toolbox. Tools that the agent previously connected to directly, including CRM, Work IQ, and Web Search, move into a toolbox, while the code connects only to its MCP (Model Context Protocol) endpoint.

The point of Toolbox is not simply to put several tools in one box. It turns tool integration that was scattered across agents into a reusable, versioned, centrally governed service layer. With Tool Search, it also replaces “give the model the full tool list” with “search by intent, then expose a small candidate set.”

In the direct-connection version of the demo, the agent owns several tool definitions and connections. Creating another similar agent means configuring tools, credentials, approval policies, and error handling again.

With Toolbox, the boundary changes in three layers:

Toolbox is created in Foundry, but consumers are not limited to Foundry agents. Any MCP-compatible runtime can connect to it, including Microsoft Agent Framework, LangGraph, and custom agents. It is better understood as a governed tool service layer than as another subagent that performs business reasoning. See the official Toolbox overview.

Toolbox standardizes the consumption interface and management model; it does not turn every direct tool into a toolbox-managed tool. Before migrating, check the official supported-tools matrix, as well as regional availability, model compatibility, and authentication requirements.

In the video, the toolbox uses the Work IQ SharePoint

MCP entry from the catalog, not Foundry's direct SharePoint tool. Both contain “SharePoint” in the name, but they sit at different interface layers. That is not evidence that a direct tool can be moved into Toolbox unchanged.

Putting several tools in a toolbox first reduces integration complexity on the agent side: the consumer only needs to know one endpoint. But without Tool Search, the MCP tools/list

method still has to expose the toolbox's tools to the client. A single endpoint does not, by itself, mean that the model context contains only one tool schema.

Tool Search is what changes the context size. When {"type": "toolbox_search"}

is enabled, Toolbox hides ordinary, unpinned tools from the initial tools/list

response and adds two meta-tools: tool_search

: the model describes the capability it needs in natural language.call_tool

: the model invokes a discovered tool by name.Tool Search uses BM25 to match against tool names, descriptions, and parameter information. It returns up to five candidates by default, with a maximum of 10. The model can search more than once in a turn, and returned tools remain callable for the rest of that turn. See Enable tool search in a toolbox.

This hiding rule applies only to tools inside the toolbox. Tools attached directly to the agent remain in the initial list. If migration leaves duplicate direct tools in place, the integration may work, but the expected context reduction may not fully materialize.

The official screen shown at the end of the video highlights a striking result: in an evaluation over an open-source dataset with an average of 600+ tools and Tool Search enabled, input tokens per call fell from 313k+ to 18k, a stated 94% reduction. Tool-selection accuracy rose from 48.2% to 52.4%. Three qualifiers matter: 600+ tools, Tool Search, and a specific evaluation dataset. This was not a measurement from the meeting-preparation agent in the video, and it does not guarantee a 94% reduction for every workload.

For an agent with only five to ten stable tools, another search round trip may not be worthwhile. The official guidance primarily targets toolboxes with more than roughly 10–15 tools, or agents whose tasks use different subsets of a larger tool catalog. Smaller agents can still benefit from Toolbox through centralized connections, reuse, and version governance even without Tool Search. Tool Search is not a magic router. Because matching depends on names, descriptions, and parameters, tool metadata becomes part of the retrieval index rather than a note written only for developers.

For the customer-meeting agent in the video, a get_customer tool described only as “Get data” is unlikely to match an intent such as “find a customer's opportunities, contacts, and renewal risk” reliably. A useful description should identify the business object it reads, the tasks it supports, key inputs, and whether it has side effects. If the team uses its own terminology, additional_search_text

can add synonyms without changing the MCP server's original schema.

For tools used on nearly every turn, configure pin: true to avoid an extra search round trip. Foundry can also automatically pin frequently used tools based on each user's call history. In either case, more tools in the initial list mean more context, which reduces the benefit of Tool Search.

pin

and additional_search_text

control how tools are discovered. They do not grant extra permissions or make high-risk write operations safe by themselves.

Toolbox can centralize credential injection, OAuth identity passthrough, guardrails, and versions, but production design still needs to distinguish content protection from call authorization.

Guardrails provide content protection. According to the documentation, an RAI policy attached to a Toolbox version checks tool inputs and outputs at the Toolbox layer, independently of model-level content filters. It does not replace downstream RBAC, OAuth scopes, or business authorization.

Approval, by contrast, must be enforced by the runtime. When a tool is configured with require_approval: "always"

, Toolbox marks the approval requirement in the metadata returned by tools/list

; the MCP endpoint itself does not block a client from issuing tools/call

. The agent runtime must present the pending action and wait for user confirmation. If a custom runtime ignores that metadata, the approval policy is not enforced. See Create and manage a toolbox.

A Toolbox version is an immutable snapshot. The first version becomes the default_version

; creating later versions does not automatically switch the default. Foundry provides two endpoint types:

`/versions/{version}/mcp`

for testing a specific version.`default_version`

.This lets a team validate the tool list, Tool Search matches, OAuth, approvals, and negative cases in v2 before promoting v2 to the default. Agents connected to the consumer endpoint do not need code changes or redeployment.

Centralization also increases blast radius. If ten agents share one consumer endpoint, an incorrect default-version promotion can affect all ten. A toolbox should not grow into an unlimited company-wide collection of tools. Split it by business capability and permission boundary instead: sales-read-toolbox

, `customer-briefing-toolbox`

, and `crm-write-toolbox`

.

Do not judge Tool Search from one successful conversation. Prepare test prompts that cover common tasks, synonyms, similar tools, and tasks for which no tool is available. Define the expected tool for each prompt, then compare direct tools with Toolbox on candidate hit rate, incorrect-selection rate, input tokens, extra search calls, and end-to-end latency. Record search queries, actual tool calls, failure reasons, and the version under test. Only your task distribution can answer whether Tool Search is worth enabling; the official 94% figure is a reference point for large tool collections.

For one agent with a small, stable toolset and no need for cross-team reuse or centralized governance, direct tool attachment may be simpler. Toolbox usually starts paying off when you add the second agent, the second team, or the first tool upgrade.