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	909	100	89%	166–167, 322, 324, 342–344, 351, 369, 383, 390, 397, 413, 415, 422, 459, 484, 488, 505–507, 554–556, 578, 632, 654, 717–723, 759, 770–781, 803–805, 810, 814, 828–830, 869, 938, 948, 958, 1014, 1045, 1064, 1342, 1399, 1419, 1490–1494, 1570–1571, 1576, 1588, 1634, 1636–1638, 1640, 1729, 1733, 1757, 1783, 1785, 1801, 1803, 1888, 1918, 1938, 1940, 1993, 2056, 2247–2248, 2296, 2364–2365, 2423, 2428, 2435
TOTAL	22207	2771	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4678	247 💤	0 ❌	0 🔥	1m 17s ⏱️

[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.

[markwallace-microsoft]

@suneetnangia, friendly reminder — this issue is waiting on your response. Please share any updates when you get a chance. (This is an automated message.)

[eavanvalkenburg]

We've had some updates to the way things are passed to functions, now using a context object, we can add this feature in there to make this a bit more firstclass, if you can have a look at that then we can get this in, I like it!

[eavanvalkenburg]

needs a update of the sample, but the rest looks good.

[eavanvalkenburg]

we now have the concept of FunctionInvocationContext, I think we should add a field for tools in there, that can be set to the AdditiveToolsList class (and maybe just call it ToolsList).

[eavanvalkenburg]

Thank you so much @suneetnangia for driving this feature and for your patience through the reviews! 🙏 As discussed, we've reworked the approach on top of the new FunctionInvocationContext to make progressive tool exposure first-class (live context.tools plus add_tools/remove_tools helpers). Closing this in favor of the superseding PR #6233, which carries your idea forward. Really appreciate the contribution!