You create version 2 of a toolbox that adds a new tool.

How it works

Toolboxes have two kinds of endpoint, and the difference is the whole answer:

• Consumer endpoint: {project_endpoint}/toolboxes/{toolbox_name}/mcp. Agents connect here, and it always serves the toolbox's default_version.
• Developer (version-specific) endpoint: .../toolboxes/{toolbox_name}/versions/{version}/mcp. It's for testing or validating a specific version before you promote it.

Versions are immutable snapshots of a toolbox's tool configuration. Every create call produces a new version, and creating a new version doesn't automatically promote it. You decide when to update default_version. The first version of a new toolbox becomes the default automatically, which is why the agents are still on version 1.

So the steps are:

1. Validate version 2 on its version-specific endpoint (list its tools, run one request that calls the new tool).
2. Promote version 2 to default_version, for example with azd ai toolbox publish.
3. Every agent on the consumer endpoint picks it up, with no code change or redeployment.

The other options, and when you'd use them

• Delete version 1: Deleting a version doesn't promote another one. The default_version field controls which version the endpoint serves, and you change it by promoting, not by deleting.
• Point every agent at the version-specific endpoint: That endpoint is reserved for testing a version before you promote it. Rewiring the agents also breaks the no-code-change rule.
• Edit version 1 in place: Toolbox versions are immutable snapshots. Changes always create a new version.

Exam tip

New toolbox version not showing up = promote it to default_version. Consumer endpoint serves the default; the version-specific endpoint is for testing.

References

• Create and manage a toolbox in Microsoft Foundry - Microsoft Foundry
• What is Toolbox in Microsoft Foundry? - Microsoft Foundry