Create and manage a toolbox in Microsoft Foundry

When you connect to non-Foundry tools, you might incur costs and data might be sent outside Foundry’s compliance boundary and processed according to the applicable terms and data handling policies. See the tool’s documentation to learn how to manage access to the tool.

This article shows you how to create a toolbox, add and configure tools, verify that they load, integrate the toolbox into a hosted agent, and manage toolbox versions. For a conceptual introduction to toolboxes, see What is Toolbox in Foundry?. For tool configuration syntax and authentication options for each tool type, see Configure tools.

Prerequisites

An active Microsoft Foundry project.
RBAC: Grant the Foundry User role on the Foundry project to each identity that applies to your scenario:
- Developer (always required) — the identity that creates, updates, and manages toolbox versions.
- Agent identity (required if using a prompt agent) — the agent’s managed identity that calls tools at runtime.
- End user (required only for OAuth flows) — any user whose identity is proxied through OAuth or UserEntraToken connections (for example, OAuth-based MCP or user Entra token (managed user identity passthrough) flows).
For step-by-step instructions to assign the Foundry User role to an agent identity, see Assign permissions to the agent identity.
Your Foundry project needs to be at one of the supported regions. Individual tool types within a toolbox are further limited by region and model – not all tool types are available in every region or with every model. See Region and model compatibility.
Visual Studio Code (VS Code).
Install the Microsoft Foundry Toolkit for Visual Studio Code extension from the Visual Studio Code Marketplace.
Python SDK: pip install azure-ai-projects azure-identity

.NET SDK: Install the coherent preview package set and Azure Identity:

dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
dotnet add package Azure.AI.Projects.Agents --version 2.1.0-beta.4
dotnet add package Azure.AI.Extensions.OpenAI --version 2.1.0-beta.4
dotnet add package Azure.Identity

JavaScript SDK: npm install @azure/ai-projects @azure/identity

Azure Developer CLI: Install the Azure Developer CLI (azd, 1.25 or later) and the unified Foundry CLI extension bundle:

# Install the unified bundle (provides azd ai agent, connection, inspector,
# project, routine, skill, and toolbox).
azd ext install microsoft.foundry

A toolbox supports at most one tool without a name field (Web Search, Azure AI Search, Code Interpreter, File Search). To include more than one instance of the same tool type, set a unique name on each instance to differentiate them. Including two instances of the same type without a name returns an invalid_payload error. For details, see Multiple tool types.
Add a description to every tool in your toolbox to help the model select the right tool for each request.
Carefully review each tool’s documentation to learn more about individual tool setup, limitations, and warnings.

If you’re using GitHub Copilot for Azure to scaffold a hosted agent that consumes the toolbox, the following skill references describe the same endpoint contract (env var, headers, MCP protocol, citation patterns, and troubleshooting) that the agent must implement:

Toolbox reference for guidance on endpoint format, MCP protocol, OAuth consent handling, citation patterns, and troubleshooting.
Use toolbox in a hosted agent to find guidance on endpoint resolution, env-var contract, payload shape, code integration patterns, and tracing.

Quick path

Create: Create a toolbox version with one or more tools. Keep each snippet focused on one task and within 30 lines; use the linked maintained samples for complete applications.
Publish or select a version: The first version becomes the default automatically. For later versions, test and promote a version when you’re ready to make it the default.
Attach and consume: Copy the toolbox consumer endpoint, and then integrate it into your agent.
Verify: Use the version-specific endpoint to list the available tools, and then run one agent request that calls an expected tool.

Feature support

SDKs and tooling support toolbox management operations, as shown in the following table.

Operation	Python SDK	REST API	.NET SDK	JavaScript SDK	Azure Developer CLI	Foundry Toolkit
Toolbox update, list, get, and delete	✔️	✔️	✔️	✔️	N/A	✔️
Toolbox version create	✔️	✔️	✔️	✔️	✔️	✔️
Toolbox version list, get, and delete	✔️	✔️	✔️	✔️	N/A	No. UI shows the latest version only.
Guardrail (RAI policy)	✔️	✔️	✔️	✔️	✔️	✔️

You can also manage toolboxes conversationally with Foundry MCP Server. See Manage toolboxes with Foundry MCP Server. You can add the following tools to a toolbox. This table shows SDK and tooling support for each tool and whether the tool can also be attached directly to an agent (outside a toolbox). For how each tool’s traffic flows when your project uses network isolation, see Network isolation for a toolbox.

Tool	In a toolbox	Direct tool integration	Python SDK	REST API	.NET SDK	JavaScript SDK	Azure Developer CLI	Foundry Toolkit
Model Context Protocol (MCP)	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	✔️
Web search	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	✔️
Azure AI Search	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	✔️
Code interpreter	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	✔️
File search	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	✔️
OpenAPI	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	No
Agent-to-agent (A2A)	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	No
Browser automation	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	No
Fabric IQ	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	✔️
Work IQ	✅ Yes	✅ Yes	✔️	✔️	✔️	✔️	✔️	✔️
Tool search	✅ Yes	❌ No	✔️	✔️	✔️	✔️	✔️	✔️
Skills	✅ Yes	❌ No	✔️	✔️	✔️	✔️	✔️	No

Tool availability also depends on your project’s region and model. Before you deploy a toolbox, verify that your target region supports the tool types you plan to use. See Tool support by region and model.

Create a toolbox version

Create a toolbox version based on the tools you need.

Get the toolbox MCP endpoint

Two endpoint patterns exist depending on your role:

Role	Endpoint	When to use
Toolbox developer	`{project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1`	Test or validate a specific version before promoting it to default.
Toolbox consumer	`{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1`	Connect agents to the toolbox. Always serves the `default_version`. The first version you create is automatically set as the default.

Replace the placeholders with your own values:

{project_endpoint} is your Foundry project endpoint, in the form https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>. Copy it from the Overview page of your project in the Foundry portal, or from the Endpoint URL column in the Toolboxes view of the Microsoft Foundry Toolkit for Visual Studio Code.
{toolbox_name} and {version} are the toolbox name and version you created in Create a toolbox version.

Connect agents to the toolbox consumer endpoint. It always serves the default_version, so you can promote new versions without changing agent code or redeploying. Reserve the toolbox developer (version-specific) endpoint for testing a version before you promote it.

The first version of a new toolbox is automatically promoted to default_version (v1). If you need to change the default later, see Promote a version to default.

In the Microsoft Foundry Toolkit for Visual Studio Code extension, copy the toolbox consumer endpoint from the Toolboxes view.

Select Foundry Toolkit in the Activity Bar.
Under My Resources, expand Your project name > Tools.
On the Toolboxes tab, locate your toolbox.
In the Endpoint URL column, copy the endpoint.

The Endpoint URL value is the toolbox consumer endpoint. To construct a version-specific endpoint, use the developer pattern shown in the previous table.

Verify tool availability

Before running the full agent, confirm that the toolbox loads the expected tools by using an MCP client SDK against the endpoint. Use the version-specific endpoint to validate a version before promoting it to default. Check — initialize: HTTP 200. If you skip the initialize step, subsequent calls fail. Check — tools/list:

len(tools) > 0 — empty means the toolbox version wasn’t provisioned correctly.
Each tool has name, description, and inputSchema. For tool naming conventions, see the MCP specification.
inputSchema has a properties field (some MCP servers omit this field, which breaks OpenAI).

Tool names are namespaced by tool type:

Tool type	Tool name format	Example
MCP	`{server_label}.{tool_name}`	`myserver.some_tool`
OpenAPI	`{openapi_name}.{operationId}`	`weatherapi.getForecast`
A2A	The tool’s `name` (agent name), or the connection name if `name` is omitted	`myagent`
All other tool types	The `name` field value or the default tool name	`web_search`

MCP tools include a _meta.tool_configuration block containing runtime settings such as require_approval. See Enforce tool approval.
Note the exact parameter names for the call step (for example query vs queries).

Check - tools/call:

No top-level error field. If present, inspect error.code. For standard MCP error codes, see the MCP specification:
- -32006 → OAuth consent required (extract URL from error.message).
- Other codes → server-side failure.
result.content[] contains entries with "type": "text" - this is the tool output.
For AI Search, check result.structuredContent.documents[] for chunk metadata (title, url, id, score).
For File Search, check result.content[].resource._meta for chunk metadata (title, file_id, document_chunk_id, score).
For Web Search, check result.content[].resource._meta.annotations[] for URL citations (type, url, title, start_index, end_index).
For Fabric IQ, check result.structuredContent.documents[] for citation chunks. Each document includes title and url fields pointing back to the Fabric item (Ontology, data agent, or Power BI semantic model) used to ground the response.
Watch for "ServerError" in text content - the tool executed but hit an internal error.

Tool-specific tools/call argument examples:

Tool type	Arguments
AI Search	`{"query": "search text"}`
File Search	`{"queries": ["search text"]}` — or `{"queries": ["search text"], "vector_store_ids": ["<VECTOR_STORE_ID>"]}` when vector store is passed dynamically
Code Interpreter	`{"code": "print(2 ** 100)"}`
Web Search	`{"search_query": "weather in seattle"}`
A2A	`{"message": {"parts": [{"type": "text", "text": "Hello"}]}}`
Fabric IQ	Varies by exposed tool — typically `{"query": "..."}` for query tools
Work IQ	`{"message": {"parts": [{"type": "text", "text": "Hello"}]}}`
MCP	`{"query": "what is agent service"}`

Integrate the toolbox into your agent

Handle tool approval requirements

The toolbox returns a _meta.tool_configuration object into every tool entry returned by tools/list. When a tool has require_approval set to "always", the agent runtime must present the pending action to the user and wait for confirmation before invoking the tool. The MCP endpoint doesn’t block tools/call. Enforcement is entirely the agent runtime’s responsibility. After your toolbox is created and tested, connect it to an agent. The integration pattern depends on the agent type:

Hosted agent (your own code running in Foundry Agent Service): see Use a toolbox with a hosted agent for Agent Framework, LangGraph, Visual Studio Code, and Azure Developer CLI integration patterns and runtime approval requirements.

Configure `require_approval` on a tool

Set require_approval when you create a toolbox version. The MCP tool examples in Create a toolbox version show both "always" and "never" values. To set it through the SDK:

Manage toolbox versions

You can delete toolbox versions only through the Python SDK, .NET SDK, JavaScript SDK, and REST API. The Azure Developer CLI supports list, get, and publish (default-version promotion) operations.

Toolbox versions are immutable snapshots of a toolbox’s tool configuration. Every call to the create endpoint produces a new ToolboxVersionObject. The parent ToolboxObject has a default_version field that controls which version the MCP endpoint serves. Creating a new version doesn’t automatically promote it - you decide when to update default_version. This process lets you stage changes, test a new version independently, and promote it to production on your own schedule.

For the Azure Developer CLI, every mutating operation that targets the current default version — azd ai toolbox connection add/remove and azd ai toolbox skill add/remove — creates a new toolbox version that carries forward all previously attached connections and skills with the requested change applied. None of these commands automatically change default_version; run azd ai toolbox publish <toolbox-name> <version> when you’re ready to make the new version active. To inspect a pending (non-default) version, use azd ai toolbox show <name> --version <n>.

Object	Key fields	Description
`ToolboxObject`	`id`, `name`, `default_version`	The toolbox container. `default_version` points to the active version.
`ToolboxVersionObject`	`id`, `name`, `version`, `description`, `created_at`, `tools[]`, `policies`	An immutable snapshot of the toolbox’s tool list at a point in time. `policies.rai_config.rai_policy_name` specifies the optional guardrail applied to this version.

Create a new version

Each create call produces a new version. If the toolbox doesn’t exist yet, the process automatically creates it. When you create the first version of a new toolbox, the default version is v1 until you manually update to another version. The response is a ToolboxVersionObject containing the new version identifier.

List versions

Get a specific version

Promote a version to default

The MCP endpoint always serves the default_version. To switch which version is active, update the toolbox:

Delete a version

Manage toolboxes with Foundry MCP Server

Foundry MCP Server (preview) exposes toolbox management as MCP tools, so you can retrieve, version, update, and delete toolboxes from an MCP client such as GitHub Copilot in Visual Studio Code. To set up the server, see Get started with Foundry MCP Server (preview).

Tool	Access	Description
`toolbox_get`	read	Retrieve a toolbox and its current default version.
`toolbox_version_get`	read	List toolbox versions, or retrieve a specific version.
`toolbox_version_create`	write	Create an immutable toolbox version. If the toolbox doesn’t exist, this tool also creates it.
`toolbox_update`	write	Create or update a toolbox, including its default version.
`toolbox_delete`	write	Delete a toolbox.
`toolbox_version_delete`	write	Delete a specific toolbox version.

The same versioning rules apply as with the SDKs. Creating a version for an existing toolbox doesn’t change the default version. To promote a version, call toolbox_update with defaultVersion set to the new version. Before you delete the current default version, set another version as the default. Example prompts:

“Show me the customer-support-tools toolbox.”
“Get version 2 of customer-support-tools.”
“Create a new version of customer-support-tools.”
“Set version 2 of customer-support-tools as the default.”
“Set version 1 of customer-support-tools as the default, then delete version 2.”
“Delete the old-support-tools toolbox.”

For the full tool reference, see Available tools and example prompts for Foundry MCP Server.

Configure tools

Choose the tool type and authentication pattern that match your scenario. Select the tab for your preferred SDK or deployment method. Each tool’s azd tab below shows declarative toolbox YAML. To create a toolbox imperatively without an agent project, use the azd ai toolbox create --from-file workflow and apply the per-tool data shown in the following sections. To deploy a toolbox with a hosted agent, model it as an azure.ai.toolbox service in azure.yaml and wire the agent to it with uses: or toolboxes:.

Multiple tool types

A single toolbox can bundle different tool types. The following example combines Web Search, Azure AI Search, and an MCP server in one toolbox:

{
  "description": "Web search, knowledge base search, and custom MCP server",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "azure_ai_search",
      "name": "my_aisearch",
      "description": "Search internal product documentation",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<INDEX_NAME>",
            "project_connection_id": "<CONNECTION_NAME>"
          }
        ]
      }
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    }
  ]
}

Each tool type (web_search, azure_ai_search, code_interpreter, file_search) can appear at most once without a name field. To include multiple instances of the same type, set a unique name on each instance - see the next example.

Multi-tool restrictions

You can include at most one instance of each built-in tool type without a name field in a toolbox. If you include two instances of the same type without a name, the API returns:

400 invalid_payload: Multiple tools without identifiers found...

Two instances of the same tool type

Use the name field to include multiple instances of the same tool type in one toolbox. Each named instance is treated as a separate tool and must have a unique name.

{
  "description": "Two Azure AI Search indexes in a single toolbox",
  "tools": [
    {
      "type": "azure_ai_search",
      "name": "product-search",
      "description": "Search product catalog and specifications",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<PRODUCT_INDEX_NAME>",
            "project_connection_id": "<PRODUCT_CONNECTION_NAME>"
          }
        ]
      }
    },
    {
      "type": "azure_ai_search",
      "name": "support-search",
      "description": "Search support tickets and troubleshooting guides",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<SUPPORT_INDEX_NAME>",
            "project_connection_id": "<SUPPORT_CONNECTION_NAME>"
          }
        ]
      }
    }
  ]
}

Each tool type has its own toolbox configuration - connection authentication types, per-language SDK snippets, and any toolbox-specific behavior. Those details live in each tool’s reference article. See the Feature support table for a link to each tool. For toolbox-specific behavior - such as File Search dynamic vector store (parameter override) or resource-level file uploads for Code Interpreter and File Search - see the linked article for each tool.

Configure guardrails

Apply a named guardrail policy to a toolbox version to enforce responsible AI content filtering on tool inputs and outputs. The guardrail runs at the toolbox layer, independently of any model-level content filter. Reference a guardrail by its policy name, which you configure in the Foundry portal under Guardrails. Set policies.rai_config.rai_policy_name to the name of the policy when creating a toolbox version.

Attach skills to a toolbox

Attach skills to a toolbox version to make them available to agents through the toolbox MCP endpoint. Each skill reference specifies the skill name and an optional version. Omit version to use the skill’s default_version; pin a version string to use an immutable snapshot. A toolbox version can contain tools, skills, or both. The following examples create a toolbox version that contains a single skill reference. To add skills to a toolbox that already has tools, include the same tools you used in Create a toolbox version along with the skills array.

Skills attached to a toolbox must exist in the same Foundry project. Cross-project references aren’t supported.

When an agent or MCP client connects to the toolbox endpoint, skills are exposed as MCP Resources. The MCP client or agent framework must support the MCP Resources protocol to auto-discover and load skills. To verify that skills are discoverable, call resources/list on the toolbox MCP endpoint and confirm your skill names appear in the response.

Reminder

The reminder_preview tool enables a hosted agent to schedule itself to run again at a future time. When the agent calls this tool, it specifies a delay in minutes. After that delay, Foundry re-invokes the same agent on the same conversation.

Troubleshoot

Symptom	Likely cause	Fix
`tools/list` returns zero tools for MCP or A2A tools	Invalid or missing connection credentials for the remote MCP server or A2A agent. The toolbox can’t retrieve tool manifests from the remote endpoint without valid auth.	Verify the `project_connection_id` exists in your Foundry project and the credentials are correct. Try connecting to the MCP server directly to test the auth setup. If using managed identity (PMI, agent identity, or MI), verify the correct RBAC role assignments for the caller on the target resource.
`tools/list` returns zero tools for OpenAPI tools	Invalid OpenAPI spec. The toolbox constructs the tool manifest from the spec, which fails if the spec is malformed.	Validate your OpenAPI spec content. Check that it conforms to OpenAPI 3.0 or 3.1 and includes valid `paths`, `operationId` values, and parameter schemas. If using managed identity auth, also verify RBAC role assignments on the target service.
`tools/list` returns fewer tools than expected	The `allowed_tools` filter contains incorrect or misspelled tool names. Tool names are case-sensitive and must follow the MCP specification for tool names (no whitespace or special characters).	Remove `allowed_tools` temporarily and call `tools/list` to get the full tool list. Use the exact names from the response to set values for `allowed_tools`.
`tools/list` returns zero tools (other tool types)	Toolbox not fully provisioned or tool type unsupported in region. For built-in tools (Web Search, AI Search, Code Interpreter, File Search), tool manifests are constructed server-side and don’t require auth — if they return empty, the toolbox version might not be provisioned yet.	Wait 10 seconds and retry.
`400 Multiple tools without identifiers`	Two unnamed tool types in one toolbox	Keep at most one unnamed type; add `server_label` to all MCP tools.
`CONSENT_REQUIRED` (code `-32006`)	OAuth connection requires user consent	Open the consent URL in a browser and complete the OAuth flow, then retry.
`401` on MCP calls	Expired token or wrong scope	Use scope `https://ai.azure.com/.default` and refresh the token.
Tool names not matching	MCP tool names are prefixed with `server_label`	Use `{server_label}.{tool_name}` format (for example, `myserver.get_info`).
`500` on `send_ping()`	Toolbox MCP server doesn’t implement the MCP `ping` method.	Use the Microsoft Agent Framework `FoundryToolbox` class, which handles the toolbox connection. Don’t call `send_ping()` directly.
`500` on `prompts/list`	The Foundry MCP server doesn’t implement `prompts/list`.	Pass `load_prompts=False` (or equivalent) to your MCP client constructor.
`500` with non-streaming `tools/call`	Non-streaming mode (`stream=False`) isn’t supported for toolbox MCP endpoints.	Always use `stream=True` when calling toolbox MCP tools.
`500` on `tools/list`	Transient server error	Retry after a few seconds.
Environment variables overwritten at runtime	The platform reserves all environment variables prefixed with `FOUNDRY_` and might silently overwrite user-defined values.	Rename custom environment variables to avoid the `FOUNDRY_` prefix (for example, use `TOOLBOX_MCP_ENDPOINT` instead of `FOUNDRY_TOOLBOX_ENDPOINT`).

The reminder tool is available only for hosted agents. You can’t use the reminder tool with prompt agents. For full setup instructions, usage examples, and limitations, see Reminder tool for self-scheduling agents.

Region and model compatibility

Toolbox availability depends on two factors beyond the project region:

Region: Some tool types aren’t available in every region that supports the agent service. For example, a region that supports the toolbox endpoint might not support all built-in tool types.

Before deploying a toolbox, verify that your target region supports the tool types you plan to use. For the full compatibility tables, see Tool support by region and model.

What is Microsoft Foundry?

Get started

Developer tools and integrations

Models

Agents

Toolboxes

Observability

Evaluation

Create and manage a toolbox in Microsoft Foundry

Prerequisites

Feature support

Create a toolbox version

Get the toolbox MCP endpoint

Verify tool availability

Integrate the toolbox into your agent

Handle tool approval requirements

Configure `require_approval` on a tool

Manage toolbox versions

Create a new version

List versions

Get a specific version

Promote a version to default

Delete a version

Manage toolboxes with Foundry MCP Server

Configure tools

Multiple tool types

Multi-tool restrictions

Two instances of the same tool type

Configure guardrails

Attach skills to a toolbox

Reminder

Troubleshoot

Region and model compatibility

​Prerequisites

​Feature support

​Create a toolbox version

​Get the toolbox MCP endpoint

​Verify tool availability

​Integrate the toolbox into your agent

​Handle tool approval requirements

​Configure require_approval on a tool

​Manage toolbox versions

​Create a new version

​List versions

​Get a specific version

​Promote a version to default

​Delete a version

​Manage toolboxes with Foundry MCP Server

​Configure tools

​Multiple tool types

​Multi-tool restrictions

​Two instances of the same tool type

​Configure guardrails

​Attach skills to a toolbox

​Reminder

​Troubleshoot

​Region and model compatibility

​Related content

Prerequisites

Feature support

Create a toolbox version

Get the toolbox MCP endpoint

Verify tool availability

Integrate the toolbox into your agent

Handle tool approval requirements

Configure `require_approval` on a tool

Manage toolbox versions

Create a new version

List versions

Get a specific version

Promote a version to default

Delete a version

Manage toolboxes with Foundry MCP Server

Configure tools

Multiple tool types

Multi-tool restrictions

Two instances of the same tool type

Configure guardrails

Attach skills to a toolbox

Reminder

Troubleshoot

Region and model compatibility

Related content