Refresh toolbox skills and add Foundry tool catalog (connector) reference by lindazqli · Pull Request #2384 · microsoft/GitHub-Copilot-for-Azure

lindazqli · 2026-05-24T20:40:46Z

Summary

Refresh the toolbox reference skills in plugin/skills/microsoft-foundry/foundry-agent/create/references/ based on recent learnings from the toolbox/MCP integration work in microsoft/hosted-agents-vnext-private-preview and the Foundry tool-catalog connector work, and add a new reference for wiring catalog-backed / generic remote-MCP tools via project connections.

Files

toolbox-reference.md — updated
- Document TOOLBOX_ENDPOINT env contract (latest vs. pinned version)
- Call out the scope pitfall (must be https://ai.azure.com/.default, not cognitiveservices)
- CONSENT_REQUIRED (-32006) can surface on initialize too, not just tools/call
- New Multi-Tool Toolbox Constraint section (400 invalid_payload: Multiple tools without identifiers found)
- New Azure AI Search Citation Pattern section (result.structuredContent.documents[])
- New Tool naming subsection ({server_label}.{tool_name} for MCP-sourced tools)
- Expanded troubleshooting table (multi-tool conflict, 0-tool transient, missing api-version, 403 on POST)
use-toolbox-in-hosted-agent.md — updated
- Cross-link to new foundry-tool-catalog.md
- Information to Gather Before Building a Toolbox Payload checklist
- Toolbox JSON payload examples (MCP with connection, public MCP no-auth)
- Declarative azd path via azure.yaml
- Tracing pointer (APPLICATIONINSIGHTS_CONNECTION_STRING)
foundry-tool-catalog.md — new
- When to use vs. tool-mcp.md (toolbox-attached vs. prompt-agent)
- Inputs-to-gather checklist; shared ARM PUT endpoint; RBAC preflight
- Decision tree mapping user scenarios → authType + metadata.type
- Body shapes for: OAuth2+gateway_connector (Custom · Preview tiles), OAuth2+catalog_MCP (Microsoft-managed OAuth), BYO OAuth App, ProjectManagedIdentity+generic_mcp, CustomKeys+generic_mcp, UserEntraToken+generic_mcp
- Catalog API lookup guidance (asset-gallery + Logic Apps managedApis/apiOperations)
- Minimum toolbox attach + verify PowerShell recipe (POST versions → PATCH default_version → tools/list → tools/call)
- Common gotchas (string default_version, target required, ApiKey rejected, per-user OAuth consent, network-secured Foundry limits)
agent-tools.md — updated
- Add the new reference to the cross-reference list and the Tool Summary table

Notes

No code samples or behavior changes outside the references folder.
All examples follow the existing reference style (Quick Reference table, sectioned headers, troubleshooting table).
tool-mcp.md is intentionally not modified — it covers the prompt-agent path; the new file covers the toolbox-attached connector path.

- toolbox-reference.md: expand troubleshooting (multi-tool constraint, 0 tools, server_label prefix), document Azure AI Search citation pattern, call out scope pitfall, document `TOOLBOX_ENDPOINT` env contract, and add CONSENT_REQUIRED on initialize. - use-toolbox-in-hosted-agent.md: cross-link to the new connector/tool catalog reference; add information-gathering checklist before building toolbox payloads; add tracing pointer. - foundry-tool-catalog.md (new): reference for wiring catalog-backed and generic remote-MCP tools via project connections (gateway_connector / catalog_MCP / generic_mcp; OAuth2 / PMI / CustomKeys / UserEntraToken / BYO-OAuth) and the minimum toolbox attach + verify recipe. - agent-tools.md: add the new reference to the tool summary table and the cross-reference list at the top.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Documentation update expanding Foundry toolbox references with a new tool catalog reference document and additional guidance for hosted agents, multi-tool toolboxes, citation patterns, and tracing.

Changes:

Added new foundry-tool-catalog.md reference covering RemoteTool project connection shapes and an attach-and-verify recipe.
Expanded toolbox-reference.md with env contract, tool naming, multi-tool constraint, Azure AI Search citation pattern, and additional troubleshooting entries.
Added information-gathering, payload examples, declarative azd config, and tracing sections to use-toolbox-in-hosted-agent.md; cross-linked from agent-tools.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md	New reference describing RemoteTool connection shapes and verify recipe.
plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md	Adds env contract, tool naming, multi-tool constraint, citation pattern, and troubleshooting rows.
plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md	Adds gather-info table, payload samples, azd yaml, multi-tool note, and tracing section.
plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md	Adds catalog reference link and toolbox-attached tool row.

…oolbox `type` The previous Tool Summary only listed prompt-agent SDK classes and omitted Memory (which has its own tool-memory.md), OpenAPI, and A2A (both supported as toolbox `type` values). Rewrite the file as a true index that distinguishes the prompt-agent path from the toolbox path: - Single Tool Summary table now maps each tool to its SDK class AND its toolbox `type`, with connection requirements and reference. - Add inline subsections for OpenAPI and A2A (no dedicated ref files exist yet) with their toolbox payload shapes. - Note that Function Calling is prompt-agent-only (executes client-side, not available via toolbox). - Cross-link to use-toolbox-in-hosted-agent.md and foundry-tool-catalog.md.

- toolbox-reference.md: mark TOOLBOX_ENDPOINT as canonical and FOUNDRY_TOOLBOX_ENDPOINT as legacy (reviewer comment on line 32). - use-toolbox-in-hosted-agent.md: - Align Tool Catalog Docs URL with the `azure/foundry/...` style used by the Toolbox Docs row (drop `?view=foundry`). - Add a `params` block (with `securestring`) to the azd YAML example so `{{ github_pat }}` is actually defined; link to azd schema docs. - Break Tracing into a short intro + bulleted list (Local / Deployed / Per-framework instrumentation / Viewing). - foundry-tool-catalog.md: - Replace the "(2026-05 snapshot)" date with a `api-version` reference and pointer to the Cognitive Services projects REST API. - Fix the PowerShell URI: use `${tb}` instead of the redundant backtick-before-`?` form. - Source `$dp` from `FOUNDRY_PROJECT_ENDPOINT` rather than hardcoding `<account>.services.ai.azure.com`, and call out that the host varies. - Drop the `?view=foundry` query from the Tool Catalog reference link for consistency.

lindazqli · 2026-05-24T20:48:56Z

Addressed all 7 review comments in 3f2a40d:

#	File / line	Fix
1	`use-toolbox-in-hosted-agent.md` L14	Aligned Tool Catalog Docs URL to `azure/foundry/...` style and dropped `?view=foundry`.
2	`use-toolbox-in-hosted-agent.md` L98	Added a `params:` block with `securestring` so `{{ github_pat }}` is defined; linked to the azd schema.
3	`foundry-tool-catalog.md` L50	Replaced "(2026-05 snapshot)" with `api-version=2025-04-01-preview` and pointer to the Cognitive Services projects REST API reference.
4	`foundry-tool-catalog.md` L224	Replaced `$tb\`?api-version=v1`with`${tb}?api-version=v1` and added an inline comment explaining the brace form.
5	`foundry-tool-catalog.md` L195	`$dp` now sources from `$env:FOUNDRY_PROJECT_ENDPOINT` rather than hardcoding `services.ai.azure.com`; added a sentence calling out that the host varies by account/region.
6	`toolbox-reference.md` L32	Marked `TOOLBOX_ENDPOINT` as canonical and `FOUNDRY_TOOLBOX_ENDPOINT` as legacy.
7	`use-toolbox-in-hosted-agent.md` L141	Tracing rewritten as short intro + bulleted list (Local dev / Deployed / Per-framework / Viewing).

…outines) and refresh toolbox-reference (-32007, OAuth passthrough, naming) agent-tools.md - Add Tool Summary rows for Work IQ (work_iq_preview), Fabric IQ (fabric_iq_preview), Tool Search (toolbox_search_preview), Routines, Memory. - Web Search row: explain Bing Custom Search connection scopes grounding to specific domains. - Bing Grounding row: clarify N/A in toolbox; toolbox path uses web_search with custom_search_configuration. - OpenAPI row: connection=key requires project_connection_id; managed_identity does NOT (uses project MI + audience). - Add inline sections for Work IQ, Fabric IQ, Tool Search, Routines with toolbox shape, requirements, and references to public docs. - Replace all ?view=foundry URLs with /azure/foundry/ canonical form. toolbox-reference.md - Tool naming: align with public doc - only MCP tools get server_label.tool_name prefix; all other types use the entry's name field or the default. - Update OAuth CONSENT_REQUIRED error code to -32007 (was -32006) everywhere. - Add note recommending toolbox token passthrough when hitting OAuth/ARA errors with direct MCP. - Mark TOOLBOX_ENDPOINT canonical because the platform reserves FOUNDRY_-prefixed env vars. - Add Tool Search to valid multi-tool combinations (doesn't count toward unnamed-tool limit).

…namespaces, MI audience, header shapes) and refresh use-toolbox (Tool Search recommendation, comprehensive tool list) foundry-tool-catalog.md - Reframe opening: emphasize the public Tool Catalog API as the source-of-truth for discovery and prepopulating connection fields. - Replace all Logic Apps language with Connector Namespace managed MCP. The gateway_connector flow is now described as connector-namespace-managed (same service that powers Routines event sources). - Document both registries available via Catalog API: public (entityContainerId=connectors-registry-prod-bl) and private tools catalog (tenant-scoped). Always query both. - Add Catalog API field reference: entityId, annotations.name, x-ms-runtime-urls[0], x-ms-capabilities (incl. "triggers"), x-ms-operations[], x-ms-trigger, x-ms-connection-parameters, x-ms-oauth-settings. - Decision-tree updates: BYO OAuth and ProjectManagedIdentity rows can also use metadata.type=catalog_MCP to prepopulate fields. - Add connectorName (top-level + in metadata + in connectionproperties JSON string) and toolEntityId fields to the gateway_connector body. - Add audience to ProjectManagedIdentity metadata, explaining it's required for MI to acquire the right resource token. - CustomKeys: spell out that header NAME and value FORMAT come from the catalog (not "Authorization: Bearer" by default). Show examples of x-api-key / Ocp-Apim / multi-header schemes. - Add full gateway-connector flow: discover, provision OAuth app, PUT, per-user listConsentLinks roundtrip, status polling, attach to toolbox, handle CONSENT_REQUIRED (-32007) at runtime. - Update -32006 to -32007 (CONSENT_REQUIRED code). - Common gotchas: connectionproperties must be JSON string not object; metadata.audience required for MI; CustomKeys header names from catalog. use-toolbox-in-hosted-agent.md - Add prominent Recommendation - enable Tool Search section right after intro, with rationale (flat context cost), behavior, and pinning recipe. - Expand Quick Reference to include Tool Search, Work IQ, Fabric IQ, Routines doc URLs. - Replace inline "Available tool types" bullet with a full table covering mcp, web_search, azure_ai_search, code_interpreter, file_search, openapi, a2a_preview, work_iq_preview, fabric_iq_preview, toolbox_search_preview, plus adjacent notes for Memory and Routines. - Add new sample payload: large toolbox with Tool Search and tool_configs pinning. - Inputs-to-gather table: add "Many tools planned?" question; note env var should not use FOUNDRY_ prefix. - Code Integration Patterns notes: add tool-naming rule (server_label prefix only for MCP-sourced) and Tool Search exemption from multi-tool limit. - Azure.yaml sample includes toolbox_search_preview directive.

lindazqli · 2026-05-24T21:28:30Z

Pushed two commits addressing all 19 review comments plus integrating the 5 new content sources you referenced (Fabric IQ #12201, Tool Search #12202, Work IQ #12200, Routines #12257, connector namespaces / managed MCP).

Commits

09c1caf — agent-tools.md + toolbox-reference.md
b4cc7a1 — foundry-tool-catalog.md + use-toolbox-in-hosted-agent.md

`agent-tools.md` (5 comments)

L17 (Web Search): Connection column now explains that Bing Custom Search restricts grounding to specific domains.
L18 (Bing Grounding): Toolbox type column now says “— (N/A in toolbox; the toolbox path uses web_search with web_search.custom_search_configuration)”.
L21 (OpenAPI): Connection column now reads “Conditional — connection auth requires project_connection_id; managed_identity auth does NOT (uses project MI + audience)”.
L23 (missing tools): Added rows + dedicated inline sections for Fabric IQ (fabric_iq_preview), Work IQ (work_iq_preview), Tool Search (toolbox_search_preview), Routines, and Agent Memory. Each section documents the toolbox shape, requirements (BYO Entra app, M365 Copilot / Fabric licensing, scopes, server URL patterns), and points at the public docs.
L68 (OpenAPI MI): OpenAPI section explicitly notes project_connection_id is only required for connection auth; managed_identity uses the project MI + audience with no connection.

`toolbox-reference.md` (3 comments)

L46 (tool naming): Rewritten per the public doc — only mcp tools are exposed as {server_label}.{tool_name}; all other tool types use the entry’s name field value (or the default tool name). Tool Search injects tool_search and call_tool.
L51 (ARA / OAuth passthrough): Added a callout in Authentication recommending that any direct MCP wiring that hits OAuth / ARA / 401 errors be moved behind a toolbox so Foundry handles bearer acquisition, refresh, consent discovery, and per-user token passthrough.
L60 (-32006 → -32007): Updated the OAuth Consent Handling section, JSON example, and troubleshooting table to use the correct code -32007 everywhere.
Bonus: marked TOOLBOX_ENDPOINT canonical (no FOUNDRY_ prefix) because the platform reserves FOUNDRY_-prefixed env vars and may silently overwrite them.

`foundry-tool-catalog.md` (9 comments)

L3 (reframe): Opening now leads with the public Tool Catalog API as the discovery + prepopulation surface, not just the connection wiring.
L57 + global Logic Apps mentions: Removed every Logic Apps reference. The “Custom · Preview” / gateway_connector flow is now described as the Connector Namespace managed MCP — the same managed service that backs Routines event sources.
L59, L60 (catalog_MCP reusable): Decision tree updated — BYO OAuth and ProjectManagedIdentity rows now recommend metadata.type=catalog_MCP so the Catalog API can still prepopulate target, OAuth URLs, scopes, and (for MI) audience. generic_mcp is reserved for truly unlisted servers.
L67 (Catalog API + registries): Added a new Catalog API — registries, discovery, and prepopulation section. Documents the two registries (public connectors-registry-prod-bl and tenant-private), the asset-gallery endpoint shape, and the key returned fields (entityId, annotations.name, x-ms-runtime-urls[0], x-ms-capabilities incl. triggers, x-ms-operations[].x-ms-trigger, x-ms-connection-parameters, x-ms-oauth-settings).
L74 (gateway connector full steps): Added a 7-step Gateway connector full flow — discover → provision OAuth app (managed or BYO) → PUT → per-caller listConsentLinks round-trip → poll overallStatus → attach to toolbox → handle CONSENT_REQUIRED (-32007) at runtime.
L103 (connectorName): gateway_connector body now shows connectorName at three levels — top-level properties.connectorName, metadata.connectorName, and metadata.connectionproperties (which must be a JSON-encoded string, not an object — added to Common gotchas).
L141 (audience): Added metadata.audience to the ProjectManagedIdentity body shape with an explanation that it's required so Foundry requests an MI token for the correct resource; without it the MCP server returns 401.
L165 (not always Bearer): Rewrote the CustomKeys body — header name and value format come from the catalog’s x-ms-connection-parameters, with examples (x-api-key, Ocp-Apim-Subscription-Key, multi-header schemes). Removed the hardcoded Authorization: Bearer template.
Updated -32006 → -32007 here too.

`use-toolbox-in-hosted-agent.md` (2 comments)

L7 (recommend Tool Search): Added a prominent ✨ Recommendation: enable Tool Search section right under the intro. Explains the “before adding > ~5 tools” heuristic, calls out that the directive doesn’t count toward the unnamed-tool limit, and shows the pinning recipe pattern. Quick Reference table now links the Tool Search, Work IQ, Fabric IQ, and Routines public docs.
L68 (comprehensive list): Replaced the inline bullet of supported tool types with a full table covering mcp, web_search, azure_ai_search, code_interpreter, file_search, openapi, a2a_preview, work_iq_preview, fabric_iq_preview, toolbox_search_preview. Added adjacent notes for Memory and Routines, and a new sample payload demonstrating Tool Search + tool_configs pinning. Authoritative pointer to the public Toolbox doc’s “Configure tools” section.

Let me know if anything needs another pass — happy to drill into any individual change.

Routines aren't a tool - they're an agent trigger - so they don't belong in the agent tools index. Removed: - Routines row from the Tool Summary table - Inline Routines (preview) section - Routines link from the References list

…talog - Add Logic Apps managedApis GET + identityProvider→URL mapping table - Add apiOperations endpoint + inputsDefinition→agentParameters mapping - Correct gateway_connector target: https://placeholder on PUT microsoft#1, rewritten on PUT microsoft#2 - Add full register-actions (PUT microsoft#2) shape with mcpserverConfigProperties schema - Expand consent: verbatim body, ~1h TTL, portal popup lifecycle pending-true path - Document dogfood OAuth-app trap (global-test.consent host) - Add tool naming pattern <label>___<connector>_<op> + Box and Outlook verified examples - Expand PMI section with forwarder limitations (query-string drop, audience mint, -32007) - Add RBAC preflight snippet - Expand pitfalls (scopes array, BYO + catalog_MCP conflict, githubcopilot.com BYO rejection, asset-gallery thin index) - Drop dangling Routines anchor in References (routines section was removed from agent-tools)

…toolbox CLI examples

…e --default-version'

- Fix command name: 'azd ai agent connection create' (not 'azd ai connection create') - Fix flag names: --auth-type custom-keys and --custom-key (singular) - Replace single example with 5 validated kind x auth-type combos - Drop unvalidated mention of 'toolbox connection add/remove'

Copilot AI review requested due to automatic review settings May 24, 2026 20:40

lindazqli requested review from RickWinter, XOEEst, XiaofuHuang, anchenyi, ankitbko, jugonzales, tendau and vebudumu as code owners May 24, 2026 20:40

Copilot AI reviewed May 24, 2026

View reviewed changes

lindazqli added 2 commits May 24, 2026 13:46