Tools, toolboxes, and knowledge

A toolbox is a curated set of tools that Foundry exposes through one Model Context Protocol (MCP) endpoint. Agents connect to that endpoint instead of configuring every MCP server, OpenAPI API, or search tool on their own. You define the tools once, manage credentials on project connections, and reuse the same toolbox across prompt agents, hosted agents, and other MCP-compatible runtimes.

Concept 7 attached individual tools directly to a prompt agent. That works for a single agent and a small tool set. As more agents appear, each team tends to copy the same integrations, store secrets in different places, and ship agent updates when a tool endpoint changes. A toolbox moves that work to one place: add or version tools centrally, promote a tested version to default, and every agent that already points at the consumer endpoint picks up the change without a code redeploy. Microsoft warns that connecting to non-Foundry tools can add cost and send data outside Foundry's compliance boundary, so review each tool's terms before you add it.

You create a toolbox version with one or more tools (and optionally skills in preview). Each tool needs a clear description so the model can pick the right one. Built-in types such as web search, Azure AI Search, code interpreter, and file search can appear at most once without a unique name field; to add two search indexes, give each Azure AI Search entry its own name. Tool search is available only inside a toolbox: it helps agents find relevant tools when the collection grows large, and it is marked preview in Foundry's toolbox overview.

• MCP servers and OpenAPI specs for custom APIs and partner services.
• Azure AI Search, file search, and web search for retrieval and grounding.
• Code interpreter for sandboxed Python, plus browser automation where your region and model support it.
• Agent-to-agent (A2A) tools, Fabric IQ, and Work IQ for specialized data and Microsoft 365 context.
• Optional skills (preview) exposed as MCP resources for reusable multi-step workflows.

A toolbox version is an immutable snapshot of its tool list and optional guardrail policy. The first version you publish becomes the default automatically. Later changes create new versions; you test with a version-specific MCP URL, then promote the version you trust to default so production agents switch without changing their endpoint string.

• In the Microsoft Foundry Toolkit for Visual Studio Code, open Foundry Toolkit in the Activity Bar, expand your project under My Resources > Tools, and use + Add Toolbox on the Build a Custom Toolbox tab—or create a version with the SDK or Azure Developer CLI.
• Register project connections first when a tool needs credentials; the toolbox references connections by name and never embeds secrets in the toolbox definition.
• Copy the toolbox consumer endpoint from the Toolboxes tab Endpoint URL column. It always serves the current default version.
• Use the developer pattern with /versions/{version}/mcp in the URL when you need to list tools and call one tool to verify a version before promotion.
• Connect hosted agents with FoundryToolbox in Python or AddFoundryToolboxes in .NET; pass the consumer endpoint (or let the platform inject TOOLBOX_ENDPOINT at runtime).
• Before production traffic, list tools over MCP and confirm each entry has a name, description, and input schema; empty lists often mean bad connection credentials or a toolbox still provisioning.

Grant the Foundry User role on the Foundry project to the developer identity that manages toolbox versions and to the agent identity that calls tools at runtime. End users need that role only when OAuth or user Entra token flows proxy their identity into a tool. Tool availability also depends on project region and model; verify both before you deploy.

Every tool call involves two identities. The agent identity authenticates to Foundry and opens the toolbox MCP endpoint. For the downstream data call, Foundry injects credentials from the project connection—API keys, a project managed identity, the agent's own identity, or tokens that represent the signed-in user. You choose the authentication type when you create the connection in the portal or with azd ai connection create, not inside agent business logic.

• For OAuth identity passthrough on hosted agents, use FoundryToolbox or AddFoundryToolboxes so the platform forwards the current call context; do not hard-code or reuse call IDs across users.
• Consumers of agents that use OAuth passthrough need at least the Foundry Agent Consumer role; the user's Entra tenant must match the Foundry project tenant.
• Optional require_approval on MCP tools returns metadata to the agent runtime, which must ask the user before calling when set to always—the MCP endpoint itself does not block the call.

Because traffic flows through the toolbox, you can apply a named guardrail policy to a toolbox version so responsible AI filtering runs on tool inputs and outputs separately from model-level filters. You can also attach an optional AI gateway (preview) so new MCP tools created in the Foundry portal—ones that do not use managed OAuth—route through Azure API Management for rate limits, IP restrictions, and centralized logging. Gateway routing applies when the tool is created; older tools may still call MCP servers directly until you recreate them.

• Treat every tool response as untrusted input; validate structured fields before your app takes consequential action.
• Write agent instructions that name each tool, when to use it, and what to do on failure—mirror the guidance in tool best practices.
• Use tool_choice when you need deterministic behavior: none to forbid tools on a turn, auto to let the model decide, or required to force a tool call.
• Review traces (Concept 13 goes deeper) to see which tools ran and whether empty results come from bad descriptions versus bad data.

When a toolbox holds many similar tools, add decision rules in instructions (for example, search internal indexes before web search). Pin critical tools or enable tool search (preview) so the model is not sent hundreds of full tool definitions on every request.

Retrieval tools ground model answers in content you control. Concept 6 covered file upload and Azure AI Search in depth; here the focus is choosing among them inside a shared toolbox and combining them with platform knowledge features. File search bills beyond model tokens. Azure AI Search connections that use a private virtual network must authenticate with the project's managed identity—key-based auth is not supported there. Foundry IQ offers a managed knowledge base with agentic retrieval, including private networking support listed in the capability reference. Memory (preview) gives agents persistent memory across sessions—treat it as preview and decide retention and access before you enable it.

• Put file search and Azure AI Search in the same toolbox when agents need both uploaded FAQs and a large catalog index; give each search tool a distinct name and description.
• After you wire retrieval, plan evaluation: Concept 14 covers groundedness and retrieval evaluators so you can measure quality instead of guessing from sample chats.
• When connecting non-Microsoft MCP servers, read data-handling notes in the toolbox documentation before you productionize.

Picture an internal IT helper for a retail company. You create a toolbox version with Azure AI Search over the hardware catalog index, an MCP tool labeled intranet that points at the ticket API through an OAuth connection, web search for public firmware advisories, and tool search (preview) because more teams will add tools later. You test with the version-specific MCP URL, promote version 2 to default, and point a hosted agent at the consumer endpoint only. Instructions say to search the catalog before opening a ticket and to ask the employee to approve MCP actions that change account settings. When answers look wrong, you improve index content and run retrieval evaluators from Concept 14 rather than tweaking the model alone.

• Duplicate unnamed built-in tools in one version returns an invalid payload error—assign unique names when you need two indexes or two web search configurations.
• Skipping MCP initialize before tools/list fails later calls; always initialize the session when you verify manually.
• Assuming OAuth works without user consent leaves calls failing with consent-required errors until the user completes the flow.
• Deploying a tool your model or region does not support produces tool-not-supported errors even when the feature table lists the tool globally.
• Using Memory (preview) without a retention plan risks keeping sensitive session context longer than policy allows.

Concept 13 turns to observability and tracing so you can follow each tool call in production. Until then, verify toolbox versions with MCP list and call checks, keep connections and descriptions current, and promote defaults only after a version-specific test passes.

• End-to-end steps to create toolbox versions, copy MCP endpoints, verify tools, and promote defaults. Create and manage a toolbox in Foundry
• How connections carry auth types and how OAuth passthrough works for hosted agents. How toolbox authentication works in Microsoft Foundry
• Instructions, tool_choice, security practices, and troubleshooting when agents skip tools. Tool best practices for Microsoft Foundry Agent Service
• Route eligible MCP tools through an AI gateway for rate limits, IP filters, and audit logging. Govern MCP tools by using an AI gateway (preview)