Python: Fix duplicate tool names between supplied tools and MCP servers

[eavanvalkenburg]

Motivation and Context

This change closes the remaining tool-name collision paths between supplied tools and MCP-provided tools in the Python Agent Framework. Without an explicit collision check, duplicate names could still reach the final tool map and silently overwrite one another, including approval-sensitive cases.

It also adds a supported escape hatch for MCP users by allowing MCP-exposed tool names to be prefixed when two MCP servers expose the same underlying tool name.

Description

This PR hardens tool assembly before execution so distinct tools with the same exposed name now fail fast instead of silently replacing one another.

The core agent runtime now performs single-pass duplicate-name checks while merging configured tools, runtime tools, and MCP tool expansions. AG-UI applies the same behavior when collecting server tools and merging client tools so approval execution sees a consistent tool set.

On the MCP side, MCPTool and its transport subclasses now support tool_name_prefix, and _mcp.py is responsible for constructing the final exposed MCP tool names. The MCP loader also keeps allowed_tools and per-tool approval configuration working with prefixed names by storing the original and normalized MCP names in FunctionTool.additional_properties.

The PR also adds regression coverage for runtime local/MCP collisions, duplicate names across MCP servers, AG-UI collision handling, and prefixed MCP tool/prompt loading. A small sample cleanup updates samples/02-agents/skills/script_approval/script_approval.py to avoid an unnecessary f-string.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull request overview

This PR hardens tool-name collision detection in the Python Agent Framework by making duplicate tool names fail fast with a ValueError instead of silently deduplicating. It also adds tool_name_prefix support to MCP tools as an escape hatch for legitimate name collisions across MCP servers.

Changes:

• Introduced _append_unique_tools / _ensure_unique_tool_names helpers and moved _get_tool_name to _tools.py; agent runtime and AG-UI tooling now raise on duplicate tool names instead of silently dropping duplicates.
• Added tool_name_prefix parameter to MCPTool and its transport subclasses, with prefix-aware allowed_tools/approval_mode matching via additional_properties.
• Added comprehensive test coverage for collision detection, prefixed MCP tools, and updated existing deduplication tests to expect ValueError.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
_tools.py	Moved _get_tool_name here; added _append_unique_tools, _ensure_unique_tool_names, _raise_duplicate_tool_name helpers
_agents.py	Rewired tool merging to use _append_unique_tools with fail-fast duplicate detection
_mcp.py	Added tool_name_prefix support, _build_prefixed_mcp_name, prefix-aware filtering/approval, additional_properties on MCP functions
_tooling.py (ag-ui)	Replaced silent dedup with _append_unique_tools in collect_server_tools and merge_tools
test_agents.py	Added collision/prefix tests; updated merge_options tests to expect ValueError
test_mcp.py	Added tests for prefix construction, prefixed tool/prompt loading
test_tooling.py	Updated merge_tools tests to expect ValueError
script_approval.py	Removed unnecessary f-string

---

You can also share your feedback on Copilot code review. Take the survey.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui/_orchestration
_tooling.py	48	0	100%
packages/core/agent_framework
_agents.py	350	42	88%	436, 440, 502, 907, 943, 959, 1053–1057, 1131, 1262, 1278, 1280, 1293, 1299, 1335, 1337, 1346–1351, 1356, 1358, 1364–1365, 1372, 1374–1375, 1383–1384, 1387–1389, 1397–1398, 1400, 1405, 1407
_mcp.py	441	64	85%	97–98, 108–113, 124, 129, 175–176, 186–191, 201–202, 254, 263, 326, 334, 393, 502, 581, 616, 618, 622–623, 625–626, 680, 695, 713, 758, 873, 886–891, 913, 966–967, 973–975, 994, 1019–1020, 1024–1028, 1045–1049, 1196
_tools.py	822	80	90%	182–183, 342, 344, 362–364, 372, 390, 404, 411, 418, 434, 436, 443, 451, 483, 508, 512, 529–531, 578–580, 602, 658, 680, 792–798, 834, 845–856, 875–877, 881, 885, 899–901, 1240, 1260, 1336–1340, 1464, 1468, 1492, 1610, 1640, 1660, 1662, 1715, 1778, 1981–1982, 2033, 2102–2103, 2163, 2168, 2175
TOTAL	23626	2664	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5152	20 💤	0 ❌	0 🔥	1m 20s ⏱️