fix: split prompt-agent tool references into tools/prompt-agent/

plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md

@@ -57,24 +57,24 @@ For a **workflow**:
 
 If MCP tools are unavailable, use the `azure-ai-projects` SDK:
 - See [SDK Operations](references/sdk-operations.md) for create, list, update, delete code samples
-- See [Agent Tools](references/agent-tools.md) for adding tools to agents
+- See [Agent Tools](references/tools/prompt-agent/agent-tools.md) for adding tools to agents
 
 ### Step 4: Add Tools (Optional)
 
 > ⚠️ **MANDATORY:** Before configuring any tool, **read its reference documentation** linked below to understand prerequisites, required parameters, and setup steps. Do not attempt to add a tool without first reviewing its reference.
 
 | Tool Category | Reference |
 |---------------|-----------|
-| Code Interpreter, Function Calling | [Simple Tools](references/agent-tools.md) |
-| File Search (requires vector store) | [File Search](references/tool-file-search.md) |
-| Web Search (default, no setup needed) | [Web Search](references/tool-web-search.md) |
-| Bing Grounding (explicit request only) | [Bing Grounding](references/tool-bing-grounding.md) |
-| Azure AI Search (private data) | [Azure AI Search](references/tool-azure-ai-search.md) |
-| MCP Servers | [MCP Tool](references/tool-mcp.md) |
-| Memory (persistent across sessions) | [Memory](references/tool-memory.md) |
+| Code Interpreter, Function Calling | [Simple Tools](references/tools/prompt-agent/agent-tools.md) |
+| File Search (requires vector store) | [File Search](references/tools/prompt-agent/tool-file-search.md) |
+| Web Search (default, no setup needed) | [Web Search](references/tools/prompt-agent/tool-web-search.md) |
+| Bing Grounding (explicit request only) | [Bing Grounding](references/tools/prompt-agent/tool-bing-grounding.md) |
+| Azure AI Search (private data) | [Azure AI Search](references/tools/prompt-agent/tool-azure-ai-search.md) |
+| MCP Servers | [MCP Tool](references/tools/prompt-agent/tool-mcp.md) |
+| Memory (persistent across sessions) | [Memory](references/tools/prompt-agent/tool-memory.md) |
 | Connections (for tools that need them) | [Project Connections](../../project/connections.md) |
 
-> ⚠️ **Web Search Default:** Use `WebSearchPreviewTool` for web search. Only use `BingGroundingAgentTool` when the user explicitly requests Bing Grounding.
+> ⚠️ **Web Search Default:** Use `WebSearchPreviewTool` for web search. Only use `BingGroundingTool` when the user explicitly requests Bing Grounding.
 
 ## Error Handling
 

plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md

@@ -7,7 +7,7 @@ Reference for wiring a **remote tool** (catalog tile or generic MCP server) into
 Three catalog backends cooperate: the **asset-gallery** index discovers connectors, the Logic Apps **managedApis** GET supplies OAuth metadata, and the Logic Apps **apiOperations** GET supplies the operation list and input schemas. Skip these calls only for fully BYO `generic_mcp` servers — every catalog-MCP or connector-namespace flow needs all three.
 
 > 📘 For the toolbox MCP endpoint, protocol, and testing, see [toolbox-reference.md](toolbox-reference.md).
-> 📘 For prompt-agent MCP wiring (without a toolbox), see [tool-mcp.md](tool-mcp.md).
+> 📘 For prompt-agent MCP wiring (without a toolbox), see [tool-mcp.md](tools/prompt-agent/tool-mcp.md).
 
 ## When to use this reference
 
@@ -703,7 +703,7 @@ The response body for `/mcp` is plain JSON (no SSE `data:` framing) despite the
 - [Toolbox (preview)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox)
 - [Private tools catalog](https://learn.microsoft.com/azure/foundry/agents/concepts/tool-catalog#private-tools-catalog)
 - [Cognitive Services projects REST API](https://learn.microsoft.com/rest/api/aiservices/)
-- [tool-mcp.md](tool-mcp.md) — prompt-agent MCP wiring (no toolbox)
+- [tool-mcp.md](tools/prompt-agent/tool-mcp.md) — prompt-agent MCP wiring (no toolbox)
 - [toolbox-reference.md](toolbox-reference.md) — MCP endpoint, auth, testing, troubleshooting
-- [agent-tools.md](agent-tools.md) — the agent-tools index
+- [agent-tools.md](tools/prompt-agent/agent-tools.md) — the agent-tools index
 - [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md) — wiring a toolbox into a hosted agent

plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-tool-search.md

@@ -35,5 +35,5 @@ For toolboxes containing many tools, replace the full tool list passed to the mo
 
 For full fields, pinning recipes, the verify-with-`tool_search` flow, and best practices, see [Tool Search tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/tool-search).
 
-- [agent-tools.md](agent-tools.md) — tool index
+- [agent-tools.md](tools/prompt-agent/agent-tools.md) — tool index
 - [use-toolbox-in-hosted-agent.md § Recommendation: enable Tool Search](use-toolbox-in-hosted-agent.md#-recommendation-enable-tool-search)

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

@@ -0,0 +1,51 @@
+# Agent Tools
+
+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.
+
+Two delivery paths exist:
+
+- **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).
+
+> 💡 **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.
+
+## Tool Summary
+
+| Tool | Prompt-agent SDK class | Connection? | Reference |
+|------|------------------------|-------------|-----------|
+| Code Interpreter | `CodeInterpreterTool` | No | [tool-code-interpreter.md](tool-code-interpreter.md) |
+| Function calling (client-side) | `FunctionTool` | No | [tool-function-calling.md](tool-function-calling.md) |
+| File Search | `FileSearchTool` | No (vector store required) | [tool-file-search.md](tool-file-search.md) |
+| Web Search (preview) | `WebSearchPreviewTool` | 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 | `BingGroundingTool` | Yes (Bing) | [tool-bing-grounding.md](tool-bing-grounding.md) |
+| Azure AI Search | `AzureAISearchTool` | Yes (Search) | [tool-azure-ai-search.md](tool-azure-ai-search.md) |
+| MCP server (remote) | `MCPTool` | 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) | 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) | Optional | [tool-a2a.md](tool-a2a.md) |
+| Agent Memory | `MemorySearchPreviewTool` | Yes (project MI + embedding model) | [tool-memory.md](tool-memory.md) |
+| **Work IQ (preview)** | `WorkIQPreviewTool` | Yes (Work IQ BYO-Entra-app OAuth connection) | [tool-work-iq.md](tool-work-iq.md) |
+| **Fabric IQ (preview)** | `FabricIQPreviewTool` | Yes (Fabric IQ Entra-app OAuth or managed-OAuth connection) | [tool-fabric-iq.md](tool-fabric-iq.md) |
+
+> ⚠️ **Default for web search:** Use `WebSearchPreviewTool` (`type: web_search`) unless the user explicitly requests Bing Grounding or Bing Custom Search.
+
+> 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).
+
+## How to use this index
+
+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.
+
+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).
+
+## Adjacent (not a `type` in a toolbox version)
+
+- **Agent Memory** — use the `MemorySearchPreviewTool` 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
+
+- **[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

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

@@ -0,0 +1,22 @@
+# Tool — Agent-to-Agent (A2A, preview)
+
+Call another Foundry agent as if it were a tool. Useful for composing specialist agents into an orchestrator.
+
+## Toolbox shape
+
+```json
+{
+  "type": "a2a_preview",
+  "name": "<AGENT_NAME>",
+  "description": "<what this agent does>",
+  "base_url": "<AGENT_BASE_URL>",
+  "project_connection_id": "<connection_to_target_project>"
+}
+```
+
+Auth is either anonymous (for the same project) or via a project connection that holds credentials for the remote agent's host.
+
+## References
+
+- [A2A tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/agent-to-agent)
+- [agent-tools.md](agent-tools.md) — tool index

plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-azure-ai-search.md → plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-azure-ai-search.md

@@ -9,7 +9,7 @@ Ground agent responses with data from an Azure AI Search vector index. Requires
   - One or more `Collection(Edm.Single)` vector fields (searchable)
   - At least one retrievable text field with content for citations
   - A retrievable field with source URL for citation links
-- A [project connection](../../../project/connections.md) between your Foundry project and search service
+- A [project connection](../../../../../project/connections.md) between your Foundry project and search service
 - `azure-ai-projects` package (`pip install azure-ai-projects --pre`)
 
 ## Required RBAC Roles
@@ -25,7 +25,7 @@ For **keyless authentication** (recommended), assign these roles to the **Foundr
 
 ## Connection Setup
 
-A project connection between your Foundry project and the Azure AI Search resource is required. See [Project Connections](../../../project/connections.md) for connection management via Foundry MCP tools.
+A project connection between your Foundry project and the Azure AI Search resource is required. See [Project Connections](../../../../../project/connections.md) for connection management via Foundry MCP tools.
 
 ## Query Types
 
@@ -66,4 +66,4 @@ A project connection between your Foundry project and the Azure AI Search resour
 
 - [Azure AI Search tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/azure-ai-search?view=foundry)
 - [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
-- [Project Connections](../../../project/connections.md)
+- [Project Connections](../../../../../project/connections.md)

plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-bing-grounding.md → plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md

@@ -16,13 +16,13 @@ Access real-time web information via Bing Search. Unlike the [Web Search tool](t
 - A [Grounding with Bing Search resource](https://portal.azure.com/#create/Microsoft.BingGroundingSearch) in Azure portal
 - `Contributor` or `Owner` role at subscription/RG level to create Bing resource and get keys
 - `Foundry Project Manager` role on the project to create a connection
-- A project connection configured with the Bing resource key — see [connections](../../../project/connections.md)
+- A project connection configured with the Bing resource key — see [connections](../../../../../project/connections.md)
 
 ## Setup
 
 1. Register the Bing provider: `az provider register --namespace 'Microsoft.Bing'`
 2. Create a Grounding with Bing Search resource in the Azure portal
-3. Create a project connection with the Bing resource key — see [connections](../../../project/connections.md)
+3. Create a project connection with the Bing resource key — see [connections](../../../../../project/connections.md)
 4. Set `BING_PROJECT_CONNECTION_NAME` environment variable
 
 ## Important Disclosures
@@ -46,5 +46,5 @@ Access real-time web information via Bing Search. Unlike the [Web Search tool](t
 - [Bing Grounding tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/bing-grounding?view=foundry)
 - [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
 - [Grounding with Bing Terms](https://www.microsoft.com/bing/apis/grounding-legal-enterprise)
-- [Connections Guide](../../../project/connections.md)
+- [Connections Guide](../../../../../project/connections.md)
 - [Web Search Tool (default)](tool-web-search.md)