Python: Progressive Tools Exposure

[suneetnangia]

Motivation and Context

This PR enables loading tools progressively as model (S/LLM) expands on the execution plan, in the same run; in several instances model is frontloaded with too many tools, this results in lower tool selection accuracy (a known concern), bloated context and higher processing costs; this change will allow building solutions where model (S/LLM) will have access to 1000s of tools dynamically without any of the forementioned concerns.

This PR supersedes #3398 (now closed due to major changes in codebase since then)

Description

This pull request introduces dynamic tool loading capabilities to the agent framework, allowing tools to access and modify the list of available tools at runtime. This enables advanced scenarios such as loading new tools based on context or previous tool calls. The implementation is thoroughly tested, and a new sample demonstrates the feature in action.

Core framework enhancements:

• The tools list is now made available in the **kwargs of tools that accept keyword arguments, allowing tools to inspect or modify the set of available tools during execution. If the tools input is already a list, the same object is used so modifications persist. (python/packages/core/agent_framework/_tools.py) [1] [2]

Testing and validation:

• Comprehensive new async tests verify that:
  • Tools receive the tools list in kwargs and can inspect it.
  • Tools can dynamically add new tools, which are immediately available in the same agent run.
  • Modifications to the tools list persist across multiple function invocations.
  • Tools without **kwargs do not receive the tools list.
  • The mechanism works with tools requiring approval. (python/packages/core/tests/core/test_kwargs_propagation_to_ai_function.py)

Documentation and samples:

• A new sample script demonstrates dynamic tool loading, showing how a tool can add new math tools (factorial and Fibonacci) at runtime, and how the agent can use them immediately. (python/samples/getting_started/tools/function_tool_dynamic_tool_exposure.py)
• The sample is referenced in the tools section of the README for discoverability. (python/samples/README.md)

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.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_tools.py	733	87	88%	176–177, 300, 302, 319–321, 328, 346, 360, 372, 377, 379, 386, 419, 490–492, 533, 555–583, 618, 626, 867, 1119, 1176, 1180, 1259–1263, 1281, 1283–1284, 1326, 1328–1330, 1332, 1415, 1419, 1469, 1471, 1487, 1489, 1553, 1580, 1637, 1705, 1884–1885, 1912, 1920, 1933, 1943–1944, 1979, 2035, 2067
TOTAL	21177	3257	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4097	225 💤	0 ❌	0 🔥	1m 10s ⏱️

[Copilot]

Pull request overview

This PR adds “progressive tools exposure” to the Python agent framework by injecting the current tools list into **kwargs for tools that accept keyword arguments, enabling tools to dynamically add additional tools during the same agent run.

Changes:

• Core: inject a mutable tools list into tool runtime kwargs during function invocation (python/packages/core/agent_framework/_tools.py).
• Tests: add async coverage validating tools-list propagation, dynamic tool addition, persistence across invocations, and approval-mode behavior (python/packages/core/tests/core/test_kwargs_propagation_to_ai_function.py).
• Samples/docs: add a new sample demonstrating dynamic tool exposure and reference it in the samples README (python/samples/getting_started/tools/function_tool_dynamic_tool_exposure.py, python/samples/README.md).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
python/packages/core/agent_framework/_tools.py	Injects the tools list into runtime kwargs passed to tools, enabling in-run mutation for progressive exposure.
python/packages/core/tests/core/test_kwargs_propagation_to_ai_function.py	Adds tests confirming tools list is available in kwargs and that mutations persist and work with approvals.
python/samples/getting_started/tools/function_tool_dynamic_tool_exposure.py	New sample showing a tool that dynamically registers additional math tools at runtime.
python/samples/README.md	Adds the new sample to the tools samples index.