Refresh toolbox skills and add Foundry tool catalog (connector) reference (#2384)

* Update toolbox skills and add Foundry tool catalog (connector) reference

- 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.

* agent-tools.md: complete tool index incl. Memory, OpenAPI, A2A; map toolbox `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.

* Address review feedback

- 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.

* Address review: rewrite agent-tools (add WorkIQ/FabricIQ/ToolSearch/Routines) 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).

* Address review: rewrite foundry-tool-catalog (Catalog API, connector 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.

* Remove Routines from agent-tools

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

* Fold full catalog-custom-connector skill content into foundry-tool-catalog

- Add Logic Apps managedApis GET + identityProvider→URL mapping table
- Add apiOperations endpoint + inputsDefinition→agentParameters mapping
- Correct gateway_connector target: https://placeholder on PUT #1, rewritten on PUT #2
- Add full register-actions (PUT #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)

* use-toolbox-in-hosted-agent: add verified azd ai connection / azd ai toolbox CLI examples

* use-toolbox-in-hosted-agent: document validated 'azd ai toolbox update --default-version'

* use-toolbox-in-hosted-agent: only document validated azd CLI scenarios

- 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'

* address review: split agent-tools into per-tool files; trim azd ai CRUD; link typespec

- Split agent-tools.md inline sections (Code Interpreter, Function Calling, OpenAPI, A2A, Work IQ, Fabric IQ, Tool Search) into per-tool files matching the existing tool-*.md convention. agent-tools.md is now an index only (viswabalaji feedback).

- Add pointer to Azure/azure-rest-api-specs typespec main branch as authoritative source-of-truth for tool shapes (viswabalaji feedback; exact subpath TBD).

- Trim use-toolbox-in-hosted-agent.md: drop azd ai connection create / toolbox create / list / delete sections per anchenyi feedback. Keep retarget-default-version + smoke-test (operational, not setup). Point toolbox/connection CRUD at Foundry Toolkit + Portal.

* address review: fix broken foundry-samples paths

- python: samples/python/toolbox/maf -> samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox (per anchenyi)

- csharp: samples/csharp/toolbox -> samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side

- SUPPORTED_TOOLBOX_TOOLS.md -> SUPPORTED_TOOLBOX_SCENARIOS.md (renamed upstream)

Author: lindazqli

plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md

@@ -1,45 +1,52 @@
-# Agent Tools — Simple Tools
+# Agent Tools
 
-Add tools to agents to extend capabilities. This file covers tools that work without external connections. For tools requiring connections/RBAC setup, see:
-- [Web Search tool](tool-web-search.md) — real-time public web search with citations (default for web search)
-- [Bing Grounding tool](tool-bing-grounding.md) — web search via dedicated Bing resource (only when explicitly requested)
-- [Azure AI Search tool](tool-azure-ai-search.md) — private data grounding with vector search
-- [MCP tool](tool-mcp.md) — remote Model Context Protocol servers
+This file is the **index** for every tool an agent can use. For each tool, it points to a dedicated reference file, and — where the tool is also available through a [toolbox](use-toolbox-in-hosted-agent.md) — lists the toolbox `type` value.
 
-## Code Interpreter
+Two delivery paths exist:
 
-Enables agents to write and run Python in a sandboxed environment. Supports data analysis, chart generation, and file processing. Has [additional charges](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/) beyond token-based fees.
+- **Prompt agent** — the agent definition declares tool classes directly (`CodeInterpreterTool`, `MCPTool`, …). Use the SDK class column and the per-tool reference.
+- **Hosted agent via toolbox** — the agent connects to a single MCP endpoint that exposes all tools declared in a toolbox version. Use the `type` column and see [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md). For wiring the underlying project connection (catalog tile or generic remote MCP), see [foundry-tool-catalog.md](foundry-tool-catalog.md).
 
-> Sessions: 1-hour active / 30-min idle timeout. Each conversation = separate billable session.
+> 💡 **Authoritative tool shapes:** the source-of-truth for every tool's wire shape is the **Foundry Agents typespec** on the `main` branch of [`Azure/azure-rest-api-specs`](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices). When in doubt about a field name, default, or new tool type that isn't yet documented here, load the typespec directly — it's updated as tools are added/changed.
 
-For code samples, see: [Code Interpreter tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/code-interpreter?view=foundry)
+## Tool Summary
 
-## Function Calling
+| Tool | Prompt-agent SDK class | Toolbox `type` | Connection? | Reference |
+|------|------------------------|----------------|-------------|-----------|
+| Code Interpreter | `CodeInterpreterTool` | `code_interpreter` | No | [tool-code-interpreter.md](tool-code-interpreter.md) |
+| Function calling (client-side) | `FunctionTool` | — (client-side only) | No | [tool-function-calling.md](tool-function-calling.md) |
+| File Search | `FileSearchTool` | `file_search` | No (vector store required) | [tool-file-search.md](tool-file-search.md) |
+| Web Search (preview) | `WebSearchPreviewTool` | `web_search` (with optional `web_search.custom_search_configuration` for Bing Custom Search) | No (basic Bing); **Yes** for Grounding with Bing Custom Search — the connection scopes grounding to specific domains | [tool-web-search.md](tool-web-search.md) |
+| Bing Grounding | `BingGroundingAgentTool` | — (N/A in toolbox; the toolbox path uses `web_search` with `web_search.custom_search_configuration`) | Yes (Bing) — prompt-agent path only | [tool-bing-grounding.md](tool-bing-grounding.md) |
+| Azure AI Search | `AzureAISearchAgentTool` | `azure_ai_search` | Yes (Search) | [tool-azure-ai-search.md](tool-azure-ai-search.md) |
+| MCP server (remote) | `MCPTool` | `mcp` | Optional (none / static key / project MI / OAuth) | [tool-mcp.md](tool-mcp.md); toolbox attach via [foundry-tool-catalog.md](foundry-tool-catalog.md) |
+| OpenAPI tool | (n/a as a single class) | `openapi` | Conditional — `connection` auth requires `project_connection_id`; **`managed_identity` auth does NOT** (the project MI is used directly with an `audience`) | [tool-openapi.md](tool-openapi.md) |
+| Agent-to-Agent (A2A) | (n/a as a single class) | `a2a_preview` | Optional | [tool-a2a.md](tool-a2a.md) |
+| Agent Memory | `MemorySearchTool` | — (separate memory store) | Yes (project MI + embedding model) | [tool-memory.md](tool-memory.md) |
+| **Work IQ (preview)** | (n/a — server-side only) | `work_iq_preview` | Yes (Work IQ BYO-Entra-app OAuth connection) | [tool-work-iq.md](tool-work-iq.md) |
+| **Fabric IQ (preview)** | (n/a — server-side only) | `fabric_iq_preview` | Yes (Fabric IQ Entra-app OAuth or managed-OAuth connection) | [tool-fabric-iq.md](tool-fabric-iq.md) |
+| **Tool Search (preview)** | (n/a — toolbox-side configuration directive) | `toolbox_search_preview` | No | [tool-tool-search.md](tool-tool-search.md) |
 
-Define custom functions the agent can invoke. Your app executes the function and returns results. Runs expire 10 minutes after creation — return tool outputs promptly.
+> ⚠️ **Default for web search:** Use `WebSearchPreviewTool` (`type: web_search`) unless the user explicitly requests Bing Grounding or Bing Custom Search.
 
-> **Security:** Treat tool arguments as untrusted input. Don't pass secrets in tool output. Use `strict=True` for schema validation.
+> Combine multiple tools on one agent or one toolbox version. The model decides which to invoke. For multi-tool toolbox limits (at most one unnamed tool per type, unique `server_label` per MCP tool) see [toolbox-reference.md](toolbox-reference.md#multi-tool-toolbox-constraint).
 
-For code samples, see: [Function Calling tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/function-calling?view=foundry)
+## How to use this index
 
-## Tool Summary
+When you need details for a specific tool, **load that tool's reference file directly** — each one is self-contained (shape, requirements, references). Don't try to keep all tools in context at once.
 
-| Tool | Connection? | Reference |
-|------|-------------|-----------|
-| `CodeInterpreterTool` | No | This file |
-| `FileSearchTool` | No (vector store required) | [tool-file-search.md](tool-file-search.md) |
-| `FunctionTool` | No | This file |
-| `WebSearchPreviewTool` | No | [tool-web-search.md](tool-web-search.md) |
-| `BingGroundingAgentTool` | Yes (Bing) | [tool-bing-grounding.md](tool-bing-grounding.md) |
-| `AzureAISearchAgentTool` | Yes (Search) | [tool-azure-ai-search.md](tool-azure-ai-search.md) |
-| `MCPTool` | Optional | [tool-mcp.md](tool-mcp.md) |
+For the toolbox runtime contract (endpoint, auth, MCP protocol, citation patterns, troubleshooting) see [toolbox-reference.md](toolbox-reference.md). For wiring a toolbox into a hosted agent (env vars, samples, tracing) see [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md).
 
-> ⚠️ **Default for web search:** Use `WebSearchPreviewTool` unless the user explicitly requests Bing Grounding or Bing Custom Search.
+## Adjacent (not a `type` in a toolbox version)
 
-> Combine multiple tools on one agent. The model decides which to invoke.
+- **Agent Memory** — use the `MemorySearchTool` SDK class on prompt agents; for hosted agents, configure the memory store via the project (separate from the toolbox). See [tool-memory.md](tool-memory.md).
+- **Routines (preview)** — not a tool; an agent **trigger** (`schedule` / `timer` / `github_issue` / `custom`) that invokes an existing agent. Event-based routines are powered by the same **Connector Namespace** that backs catalog-MCP / managed-MCP connectors. See the [public Routines docs](https://learn.microsoft.com/azure/foundry/agents/how-to/use-routines).
 
 ## References
 
-- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
-- [Code Interpreter](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/code-interpreter?view=foundry)
-- [Function Calling](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/function-calling?view=foundry)
+- **[Foundry Agents typespec (`main`)](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices)** — authoritative tool shapes
+- [Tool Catalog](https://learn.microsoft.com/azure/foundry/agents/concepts/tool-catalog)
+- [Toolbox (preview)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox)
+- [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md) — wiring a toolbox into a hosted agent
+- [toolbox-reference.md](toolbox-reference.md) — toolbox runtime contract
+- [foundry-tool-catalog.md](foundry-tool-catalog.md) — project connections for remote tools