Python: Fix MCP tools duplicated on second turn when runtime tools are present

[Giles Odigwe (giles17)]

Summary

Fixes#4381

When AgentFrameworkAgent (from agent-framework-ag-ui) is used with an Agent that has an MCPStdioTool, and the AG-UI request includes client-side tools, the MCP tool functions are expanded twice on the second and subsequent turns - producing a tool list with every MCP tool name duplicated.

Root Cause

In _prepare_run_context (_agents.py), self.mcp_tools functions were unconditionally appended to final_tools even when they were already present from runtime tools (pre-expanded by AG-UI's collect_server_tools on turn 2 when the MCP server is connected).

Fix

Added name-based deduplication before extending final_tools with MCP server functions - collecting existing tool names first and skipping any MCP functions already present. This follows the same dedup pattern used in _merge_options.

Changes

• packages/core/agent_framework/_agents.py - 2-line fix in _prepare_run_context
• packages/core/tests/core/test_agents.py - added test_mcp_tools_not_duplicated_when_passed_as_runtime_tools

Verification

Reproduced the issue using the repro script from the issue, confirmed turn 2 no longer duplicates tools:

# Before fix:
[API call #1] 3 tools: ['client_tool', 'tool_a', 'tool_b']
[API call #2] 5 tools: ['tool_a', 'tool_b', 'client_tool', 'tool_a', 'tool_b']
# After fix:
[API call #1] 3 tools: ['client_tool', 'tool_a', 'tool_b']
[API call #2] 3 tools: ['tool_a', 'tool_b', 'client_tool']

[Mark Wallace (markwallace-microsoft)]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agents.py	343	41	88%	435, 439, 491, 856, 892, 908, 991–994, 1057, 1179, 1195, 1197, 1210, 1216, 1252, 1254, 1263–1268, 1273, 1275, 1281–1282, 1289, 1291–1292, 1300–1301, 1304–1306, 1314–1315, 1317, 1322, 1324
TOTAL	22530	2799	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4581	25 💤	0 ❌	0 🔥	1m 22s ⏱️

[Copilot]

Pull request overview

This PR fixes a bug (issue #4381) where MCPStdioTool functions are duplicated on the second and subsequent turns when AgentFrameworkAgent (AG-UI) is used with an Agent that also receives client-side tools at runtime. On turn 2, AG-UI's collect_server_tools pre-expands MCP functions (since the server is now connected) and passes them as runtime tools=, but _prepare_run_context unconditionally extended final_tools from self.mcp_tools again — doubling every MCP function.

Changes:

• Added name-based deduplication in _prepare_run_context before extending final_tools with mcp_server.functions, skipping any function already present by name.
• Added a regression test test_mcp_tools_not_duplicated_when_passed_as_runtime_tools that simulates the turn-2 scenario with a connected mock MCP tool.

Reviewed changes

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

File	Description
python/packages/core/agent_framework/_agents.py	Adds existing_names set before extending from self.mcp_tools, skipping functions already present in final_tools
python/packages/core/tests/core/test_agents.py	New regression test verifying no duplication when MCP functions are passed as runtime tools

---

There is one bug in the fix itself: the existing_names set comprehension at line 1054 uses t.name directly on all items in final_tools, but final_tools can contain Mapping/dict-based tool definitions (which pass through normalize_tools and the else branch at line 1052) that do not have a .name attribute. This would cause an AttributeError at runtime when any runtime tool is a dict-style tool definition.

The file already defines _get_tool_name(t) (lines 84–91) that safely handles both dict-based tools and attribute-based tools, and is used for exactly this purpose in _merge_options (line 110). The fix should use _get_tool_name instead of direct .name access.