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

[XiaofuHuang]

Description

Move the 13 per-tool references into references/tools/prompt-agent/ so the prompt-agent (SDK-class) docs live in one folder, ahead of adding a parallel hosted-agent (azd toolbox) set in a follow-up PR.

• agent-tools.md: scope to prompt agents; correct SDK class names against azure-ai-projects 2.3.0 (BingGroundingTool, AzureAISearchTool, MemorySearchPreviewTool, WorkIQPreviewTool, FabricIQPreviewTool, ToolSearchToolParam).
• tool-a2a.md: add the prompt-agent a2a_preview reference under prompt-agent/; the root references/tool-a2a.md (azd remote-a2a guide from fix(microsoft-foundry): hosted agents call incoming A2A agent #2846) is left in place and will move to the hosted set in the follow-up PR.
• Rewire inbound links in create-prompt.md, foundry-tool-catalog.md, and use-toolbox-in-hosted-agent.md to the new folder.

Checklist

• Tests pass locally (cd tests && npm test)
• Title has one of the prefixes: fix:, feat:, feature:, chore:, misc:, test:, eval:
• If modifying skill descriptions: verified routing correctness with integration tests (In tests/, npm run test:integration -- <skill> or npm run test:vally -- --skill <skill>)

[github-actions]

Details

# 🔍 Token Analysis Report

@github-copilot-for-azure/scripts@1.0.0 tokens
node --import tsx src/tokens/cli.ts compare --base origin/main --head HEAD --markdown

fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/agent-tools.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-a2a.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-azure-ai-search.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-code-interpreter.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-fabric-iq.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-file-search.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-function-calling.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-mcp.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-memory.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-openapi.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-web-search.md' exists on disk, but not in 'origin/main'
fatal: path 'plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-work-iq.md' exists on disk, but not in 'origin/main'

📊 Token Change Report

Comparing origin/main → HEAD

Summary

Metric	Value
📈 Total Change	+7,042 tokens (+35%)
Before	20,303 tokens
After	27,345 tokens
Files Changed	19

Changed Files

File	Before	After	Change
plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md	1,466	-	-1466
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/agent-tools.md	-	1,331	+1331
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-memory.md	-	1,205	+1205
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-web-search.md	-	924	+924
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-mcp.md	-	861	+861
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-azure-ai-search.md	-	855	+855
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md	-	715	+715
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-file-search.md	-	669	+669
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-fabric-iq.md	-	481	+481
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-work-iq.md	-	433	+433
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-openapi.md	-	383	+383
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-code-interpreter.md	-	290	+290
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-function-calling.md	-	208	+208
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-a2a.md	-	168	+168
plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md	4,288	4,213	-75 (-2%)
plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md	992	1,028	+36 (+4%)
plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md	10,891	10,905	+14 (0%)
plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-tool-search.md	504	509	+5 (+1%)
plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md	2,162	2,167	+5 (0%)

@github-copilot-for-azure/scripts@1.0.0 tokens
node --import tsx src/tokens/cli.ts check --markdown

📊 Token Limit Check Report

Checked: 726 files
Exceeded: 100 files

⚠️ Files Exceeding Token Limits

File	Tokens	Limit	Over By
.github/skills/analyze-skill-issues/SKILL.md	2109	500	+1609
.github/skills/analyze-test-run/SKILL.md	2471	500	+1971
.github/skills/file-test-bug/SKILL.md	628	500	+128
.github/skills/sensei/SKILL.md	856	500	+356
.github/skills/skill-authoring/SKILL.md	839	500	+339
.github/skills/vally-eval/SKILL.md	1757	500	+1257
plugin/skills/airunway-aks-setup/SKILL.md	1025	500	+525
plugin/skills/appinsights-instrumentation/SKILL.md	937	500	+437
plugin/skills/azure-ai/SKILL.md	820	500	+320
plugin/skills/azure-aigateway/SKILL.md	1261	500	+761
plugin/skills/azure-aigateway/references/policies.md	2342	2000	+342
plugin/skills/azure-cloud-migrate/SKILL.md	1085	500	+585
plugin/skills/azure-cloud-migrate/references/services/container-apps/cloudrun-deployment-guide.md	2029	2000	+29
plugin/skills/azure-cloud-migrate/references/services/container-apps/deployment-guide.md	2458	2000	+458
plugin/skills/azure-cloud-migrate/references/services/container-apps/fargate-deployment-guide.md	2587	2000	+587
plugin/skills/azure-cloud-migrate/references/services/container-apps/spring-deployment-guide.md	3871	2000	+1871
plugin/skills/azure-cloud-migrate/references/services/functions/lambda-to-functions.md	2600	2000	+600
plugin/skills/azure-cloud-migrate/references/services/functions/runtimes/javascript.md	2181	2000	+181
plugin/skills/azure-compliance/SKILL.md	1188	500	+688
plugin/skills/azure-compute/SKILL.md	762	500	+262
plugin/skills/azure-compute/workflows/essential-machine-management/references/emm-enable-flow.md	2344	2000	+344
plugin/skills/azure-compute/workflows/vm-troubleshooter/vm-troubleshooter.md	2509	2000	+509
plugin/skills/azure-deploy/SKILL.md	1645	500	+1145
plugin/skills/azure-deploy/references/pre-deploy-checklist.md	4692	2000	+2692
plugin/skills/azure-deploy/references/recipes/azd/errors.md	4004	2000	+2004
plugin/skills/azure-deploy/references/troubleshooting.md	2038	2000	+38
plugin/skills/azure-diagnostics/SKILL.md	1423	500	+923
plugin/skills/azure-enterprise-infra-planner/SKILL.md	911	500	+411
plugin/skills/azure-enterprise-infra-planner/references/constraints/compute-apps.md	2022	2000	+22
plugin/skills/azure-kubernetes/SKILL.md	2634	500	+2134
plugin/skills/azure-kubernetes/azure-kubernetes-automatic-readiness/SKILL.md	3690	500	+3190
plugin/skills/azure-kusto/SKILL.md	2152	500	+1652
plugin/skills/azure-messaging/SKILL.md	821	500	+321
plugin/skills/azure-prepare/SKILL.md	3145	500	+2645
plugin/skills/azure-prepare/references/aspire.md	4617	2000	+2617
plugin/skills/azure-prepare/references/plan-template.md	2560	2000	+560
plugin/skills/azure-prepare/references/recipes/azd/aspire.md	2275	2000	+275
plugin/skills/azure-prepare/references/recipes/azd/terraform.md	3555	2000	+1555
plugin/skills/azure-prepare/references/research.md	2196	2000	+196
plugin/skills/azure-prepare/references/resources-limits-quotas.md	3322	2000	+1322
plugin/skills/azure-prepare/references/security.md	2147	2000	+147
plugin/skills/azure-prepare/references/services/functions/bicep.md	3043	2000	+1043
plugin/skills/azure-prepare/references/services/functions/templates/recipes/composition.md	2813	2000	+813
plugin/skills/azure-prepare/references/services/functions/terraform.md	3404	2000	+1404
plugin/skills/azure-quotas/SKILL.md	3006	500	+2506
plugin/skills/azure-quotas/references/commands.md	2644	2000	+644
plugin/skills/azure-reliability/SKILL.md	5922	500	+5422
plugin/skills/azure-reliability/references/configure-multi-region.md	4729	2000	+2729
plugin/skills/azure-reliability/references/services/app-service/reliability.md	2591	2000	+591
plugin/skills/azure-resource-lookup/SKILL.md	1367	500	+867
plugin/skills/azure-resource-visualizer/SKILL.md	2122	500	+1622
plugin/skills/azure-storage/SKILL.md	1228	500	+728
plugin/skills/azure-upgrade/SKILL.md	1542	500	+1042
plugin/skills/azure-upgrade/references/languages/java/INSTRUCTION.md	2893	2000	+893
plugin/skills/azure-upgrade/references/languages/java/package-specific/com.microsoft.azure.management.md	2428	2000	+428
plugin/skills/azure-upgrade/references/languages/java/templates/PLAN_TEMPLATE.md	2411	2000	+411
plugin/skills/azure-upgrade/references/languages/java/templates/PROGRESS_TEMPLATE.md	2315	2000	+315
plugin/skills/azure-upgrade/references/languages/java/templates/SUMMARY_TEMPLATE.md	2190	2000	+190
plugin/skills/azure-upgrade/references/services/functions/automation.md	3463	2000	+1463
plugin/skills/azure-upgrade/references/services/functions/consumption-to-flex.md	2773	2000	+773
plugin/skills/azure-validate/SKILL.md	950	500	+450
plugin/skills/entra-agent-id/SKILL.md	3994	500	+3494
plugin/skills/entra-app-registration/SKILL.md	2058	500	+1558
plugin/skills/entra-app-registration/references/api-permissions.md	2545	2000	+545
plugin/skills/entra-app-registration/references/cli-commands.md	2211	2000	+211
plugin/skills/entra-app-registration/references/console-app-example.md	2752	2000	+752
plugin/skills/entra-app-registration/references/oauth-flows.md	2375	2000	+375
plugin/skills/microsoft-foundry/SKILL.md	6166	500	+5666
plugin/skills/microsoft-foundry/finetuning/SKILL.md	1375	500	+875
plugin/skills/microsoft-foundry/foundry-agent/azd-guidance/references/azd-ai-cli.md	2129	2000	+129
plugin/skills/microsoft-foundry/foundry-agent/create/create-hosted.md	7101	2000	+5101
plugin/skills/microsoft-foundry/foundry-agent/create/quick-start-hosted.md	5246	2000	+3246
plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md	10905	2000	+8905
plugin/skills/microsoft-foundry/foundry-agent/create/references/local-run.md	2252	2000	+252
plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md	3137	2000	+1137
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools.md	2359	2000	+359
plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md	4213	2000	+2213
plugin/skills/microsoft-foundry/foundry-agent/deploy/deploy.md	4897	2000	+2897
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/eval-datasets.md	2863	2000	+863
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/references/generate-seed-dataset.md	2212	2000	+212
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/references/trace-to-dataset.md	4325	2000	+2325
plugin/skills/microsoft-foundry/foundry-agent/invocations-ws/invocations-ws.md	2652	2000	+652
plugin/skills/microsoft-foundry/foundry-agent/observe/observe.md	3856	2000	+1856
plugin/skills/microsoft-foundry/foundry-agent/observe/references/continuous-eval.md	3855	2000	+1855
plugin/skills/microsoft-foundry/foundry-agent/observe/references/evaluate-step.md	2175	2000	+175
plugin/skills/microsoft-foundry/foundry-agent/observe/references/evaluation-suite-generation.md	3134	2000	+1134
plugin/skills/microsoft-foundry/foundry-agent/routine/routine.md	2032	2000	+32
plugin/skills/microsoft-foundry/foundry-agent/trace/references/kql-templates.md	2701	2000	+701
plugin/skills/microsoft-foundry/models/deploy-model/SKILL.md	1805	500	+1305
plugin/skills/microsoft-foundry/models/deploy-model/capacity/SKILL.md	1739	500	+1239
plugin/skills/microsoft-foundry/models/deploy-model/customize/SKILL.md	2235	500	+1735
plugin/skills/microsoft-foundry/models/deploy-model/customize/references/customize-workflow.md	3335	2000	+1335
plugin/skills/microsoft-foundry/models/deploy-model/preset/SKILL.md	1226	500	+726
plugin/skills/microsoft-foundry/models/deploy-model/preset/references/preset-workflow.md	5534	2000	+3534
plugin/skills/microsoft-foundry/project/create/create-foundry-project.md	2283	2000	+283
plugin/skills/microsoft-foundry/quota/quota.md	2288	2000	+288
plugin/skills/microsoft-foundry/quota/references/capacity-planning.md	2080	2000	+80
plugin/skills/microsoft-foundry/references/agent-metadata-contract.md	2217	2000	+217
plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md	2167	2000	+167
plugin/skills/python-appservice-deploy/SKILL.md	688	500	+188

Consider moving content to references/ subdirectories.

---

Automated token analysis. See skill authoring guidelines for best practices.

[Copilot]

Pull request overview

This PR reorganizes Microsoft Foundry agent documentation by moving per-tool reference docs into references/tools/prompt-agent/, so prompt-agent (SDK-class) tool documentation is consolidated ahead of adding a separate hosted-agent (toolbox/azd) doc set.

Changes:

• Refactors agent-tools.md to be explicitly prompt-agent scoped and updates SDK class names/links to the new tools/prompt-agent/ folder.
• Adds/updates prompt-agent per-tool reference pages under references/tools/prompt-agent/ and fixes internal relative links between them.
• Rewires inbound links (e.g., from create-prompt.md and foundry-tool-catalog.md) to point to the new prompt-agent tool reference paths.

Reviewed changes

Copilot reviewed 15 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md	Removes references to the old per-tool docs in favor of public docs + in-file table (but needs link fixes).
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-work-iq.md	Updates relative links to hosted-agent boundary guidance and reference index pages.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-web-search.md	Adds a dedicated prompt-agent Web Search tool reference page.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-tool-search.md	Updates references to the prompt-agent tool index and hosted-agent toolbox guidance.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-openapi.md	Fixes relative link to toolbox-reference.md and index references after the move.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-memory.md	Updates Memory tool class naming to MemorySearchPreviewTool.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-mcp.md	Fixes relative links to the central Project Connections guide after relocation.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-function-calling.md	Updates link to the prompt-agent tool index location.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-file-search.md	Adds a dedicated prompt-agent File Search tool reference page.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-fabric-iq.md	Updates links to the prompt-agent tool index and tool catalog reference.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-code-interpreter.md	Updates links to the prompt-agent tool index and toolbox reference.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md	Updates links to the Project Connections guide after relocation.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-azure-ai-search.md	Updates links to the Project Connections guide after relocation.
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-a2a.md	Adds a prompt-agent A2A preview tool reference page.
plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md	Rewires prompt-agent MCP wiring link to the new prompt-agent tool reference location.
plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md	Re-scopes the index to prompt agents and points tool references to tools/prompt-agent/.
plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md	Rewires tool reference links to the new prompt-agent docs (but Project Connections link needs correction).

[RickWinter]

This PR separates prompt-agent tool references from the hosted-agent guidance. The hosted-agent memory link now points to a prompt-agent-only reference that instructs readers to attach a prompt SDK class, so that distinction needs resolving before merge. No other blockers were identified.