Python: document progressive tool exposure and tool-ordering enforcement

[moonbox3]

PR #6233 (merged 2026-06-03, first shipped in python-1.8.0) added progressive tool exposure to the Python function-calling loop, but the only documentation today is a two-sentence entry in the Learn upgrade notes (python-2026-significant-changes). The feature needs proper conceptual docs. This also keeps coming up from users, most recently in discussion #6386 (enforcing tool execution order without a workflow), so the docs should cover that use case explicitly.

What #6233 added:

• FunctionInvocationContext gains a live, mutable tools list representing the current run's tool set.
• Experimental add_tools() / remove_tools() helpers (feature id PROGRESSIVE_TOOLS, emits ExperimentalWarning on first use). Any tool that declares a FunctionInvocationContext parameter (injected, never shown to the model), or any function middleware, can mutate the list.
• Mutations take effect on the next iteration of the function-calling loop; tool calls already requested in the in-flight batch still execute.
• Inputs are normalized via normalize_tools; re-adding the same tool object is a no-op, a different tool with a duplicate name raises ValueError. Calling the helpers outside a function-calling loop raises RuntimeError.
• Sample: python/samples/02-agents/tools/dynamic_tool_exposure.py plus a samples/02-agents/tools/README.md index.
• Not covered for CodeAct providers (agent-framework-monty / agent-framework-hyperlight), where the model sees a single code-execution surface rather than individual tool schemas.

Docs needed (Learn, agent-framework section):

1. A new page under agents/tools (suggested title: "Controlling tool availability") covering the three related primitives together:
   • Progressive tool exposure: loader-tool pattern (start small, pull tools in on demand) and the gating pattern (hide a dependent tool until its precondition tool has run). Include the work-item example from discussion How to Enforce Tool Execution Order in an Agent (AG-UI) #6386: register only get_work_item, have it ctx.add_tools(update_work_item) on success.
   • Function middleware gating: setting context.result without calling call_next() to reject a call and return corrective feedback to the model, for argument-level checks (for example, the update must target the same id that was fetched).
   • Forcing a call via tool_choice with {"mode": "required", "required_function_name": ...}, including that the loop resets tool_choice after the first iteration.
2. Document the semantics and caveats listed above: next-iteration effect, in-flight batch behavior, duplicate-name and outside-loop errors, experimental status, per-run scope (the tool list resets on each run, so gates re-arm every turn), and the CodeAct exclusion.
3. Cross-link from the existing function-tools and middleware pages, and link the new page from the upgrade-notes entry.
4. Position relative to workflows: a short note that pairwise ordering constraints do not require a workflow; workflows are for genuine multi-step orchestration.

Reference answer showing the full pattern end to end: #6386 (comment)