foundry-agent/toolbox/references/toolbox-azd.md
Manage Tools & Toolboxes with azd ai
The full azd ai toolbox CLI surface — creating, editing, versioning, and teardown. For the create→consume walkthrough and per-tool flows, see toolbox.md § Create & use a toolbox (happy path) and the Supported tool types table.
CLI surface
| Command | What it does |
|---------|--------------|
| azd extension install azure.ai.toolboxes | Install the toolbox CLI extension (once). |
| azd ai toolbox create <name> --from-file <path> | Create toolbox + its first version. File must list at least one connection, skill, or tool. |
| azd ai toolbox connection add <toolbox> <connection> [--index ...] [--instance-name ...] | Attach one; creates a new version (default unchanged). |
| azd ai toolbox connection add <toolbox> --from-file <path> | Attach many connections in one call; ONE new version (default unchanged). Connectionless built-ins aren't supported here — see the note under --from-file schema. |
| azd ai toolbox connection remove <toolbox> <connection> | Detach; creates a new version (default unchanged). Refuses to leave zero tools. |
| azd ai toolbox show <name> [--version <ver>] | Show toolbox + MCP endpoint URL. |
| azd ai toolbox list | List toolboxes. |
| azd ai toolbox versions list <toolbox> | List versions. |
| azd ai toolbox publish <name> <version> | Promote a version to default (also used to roll back). |
| azd ai toolbox delete <name> [--version <ver>] [--force] | Delete toolbox or one version. |
Every mutation publishes a new immutable version but does not change the default; run azd ai toolbox publish <name> <version> to promote one.
--from-file schema
The YAML/JSON passed to azd ai toolbox create --from-file lists the connections to bundle, plus an optional tools: block for connectionless built-ins.
Note:
azd ai toolbox connection add --from-fileattaches connections only. Connectionless built-ins (thetools:block —web_search,code_interpreter,file_search,toolbox_search_preview) can't be added to an existing toolbox; recreate it withazd ai toolbox create --from-fileand the full desired tool set.
description: research toolbox # only on `create`
connections:
- name: my-mcp # RemoteTool
- name: my-search # CognitiveSearch -- needs index
index: products
- name: my-a2a # RemoteA2A
tools: # connectionless built-ins (optional)
- type: web_search
name: web
- type: code_interpreter
container: { type: auto }
- type: file_search
vector_store_ids: ["<vector-store-id>"] # flat: sibling of type, NOT nested under file_search
- type: toolbox_search_preview
descriptionis honored only oncreate(it names the first version).- At least one of
connections,skills, ortoolsmust be non-empty. - The
connections:block is a CLI convenience alias — the CLI expands each entry into the corresponding nested tool (e.g.CognitiveSearch→ anazure_ai_searchtool). The raw toolbox API accepts only thetools:array, so a hand-rolled API payload must use the tool shape directly. - Attaching many entries in one
--from-filecall produces one new version.createpublishes it as the first (default) version;connection addleaves the default unchanged until youpublish.
Per-connection-kind fields
| Connection kind | Extra field(s) | Notes |
|-----------------|----------------|-------|
| RemoteTool (MCP) | — | Just name. |
| CognitiveSearch (Azure AI Search) | index | One entry per index; repeat with different index values for multiple indexes. |
| RemoteA2A (A2A peer) | — | Just name. |
Connectionless built-in tools (tools: block)
Built-ins with no connection are declared directly under tools: (not connections:):
| type | Extra field(s) | Notes |
|--------|----------------|-------|
| web_search | — | Basic Bing. For Bing Custom Search, use a GroundingWithCustomSearch connection instead. |
| code_interpreter | container: { type: auto } | Sandboxed Python. |
| file_search | vector_store_ids | Flat: vector_store_ids: ["vs_..."] as a sibling of type (NOT nested under file_search:). Requires an existing vector store ID. |
| toolbox_search_preview | — | Tool Search directive; counts as the toolbox's one allowed unnamed tool. |
Client-side function calling (
FunctionTool) is not a toolbox tool type — it's declared on the prompt agent directly.
Multi-tool rule
Across the whole toolbox, at most ONE tool may be unnamed. Every other tool needs a unique identifier — name for built-ins, server_label for mcp (and, for openapi, a distinct info.title in each spec — see below). toolbox_search_preview counts as a tool here. Violating this returns 400 invalid_payload: Multiple tools without identifiers found. All tools except a single tool must have unique identifiers ('name' or 'server_label').
Valid combinations include:
file_search(unnamed) + one or moremcp(each with uniqueserver_label)web_search(unnamed) + one or moremcpazure_ai_search(unnamed) + one or moremcpweb_searchnamed (name: web) +toolbox_search_preview(the one unnamed tool)
Multiple openapi entries are allowed in one toolbox only if each entry's spec defines a distinct info.title (the title is the implicit identifier).
Connection-backed tools and connectionless built-ins can be bundled in one --from-file (built-ins go under a tools: block, not azd ai toolbox connection add) — one new version regardless of count.
References
- toolbox.md — concept, create flow, supported tool types, troubleshooting
- Toolbox (Configure tools)
- Tool Catalog
- Foundry Toolkit (VS Code) — set up tools/toolboxes
- Foundry Portal