[Roger Barreto (rogerbarreto)]

Motivation & Context

Some XML comments incorrectly imply that startup toolbox discovery failures make readiness unhealthy or that healthy readiness guarantees every toolbox is available. Correct these comments to match the implementation, which defers non-cancellation discovery failures for per-request resolution.

Description & Review Guide

• What are the major changes? Correct XML comments in FoundryToolboxStartupStatus, FoundryToolboxService, FoundryToolboxHealthCheck, and AddFoundryToolboxes. Explain pending startup and its configured failure status, healthy results after normal startup, deferred discovery, consent requirements, endpoint fallback, and cancellation propagation. Document that the current implementation leaves FailedToolboxNames empty and does not produce Unhealthy during normal startup.
• What is the impact of these changes? Documentation only. No runtime behavior, public API signatures, or enum values change. Healthy toolbox readiness does not guarantee that every toolbox is available, that other checks pass, or that host startup succeeds.
• What do you want reviewers to focus on? Accuracy of startup exception handling and health-check mapping, particularly cancellation leaving startup pending without guaranteeing an accessible readiness endpoint.

Local validation:

• dotnet build dotnet\tests\Microsoft.Agents.AI.Foundry.Hosting.UnitTests\Microsoft.Agents.AI.Foundry.Hosting.UnitTests.csproj -c Debug -f net10.0 --no-restore --tl:off --warnaserror: passed, zero warnings or errors.
• From dotnet: dotnet test --project tests\Microsoft.Agents.AI.Foundry.Hosting.UnitTests\Microsoft.Agents.AI.Foundry.Hosting.UnitTests.csproj -c Debug -f net10.0 --no-build --no-restore: passed, 644 succeeded, one existing skipped test, zero failed.
• dotnet format dotnet\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj --no-restore --verify-no-changes --include dotnet\src\Microsoft.Agents.AI.Foundry.Hosting\FoundryToolboxStartupStatus.cs dotnet\src\Microsoft.Agents.AI.Foundry.Hosting\FoundryToolboxService.cs dotnet\src\Microsoft.Agents.AI.Foundry.Hosting\FoundryToolboxHealthCheck.cs dotnet\src\Microsoft.Agents.AI.Foundry.Hosting\ServiceCollectionExtensions.cs --verbosity diagnostic: passed, zero files formatted. Native Windows verification used because the Docker daemon was unavailable; container CI parity was not run.
• git diff --check: passed. Also verified well-formed XML, preserved UTF-8 BOM, and unchanged non-documentation lines. Full-solution and integration tests were not run for this XML-only correction.

Related Issue

N/A - trivial change. Correct existing XML documentation to match the current implementation without changing behavior or APIs.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Copilot assisted with XML documentation corrections, source verification, local validation, and this PR description. The documentation proposal was reviewed and approved before publication.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟢 Approval recommended

There are no active review issues for the toolbox startup and readiness documentation changes.

No open issues 🎉

What changed in this PR

Clarifies .NET Foundry toolbox XML documentation to match existing startup and readiness behavior. No runtime behavior, public API signatures, or enum values change.

Changes:

• Explains that healthy toolbox readiness does not guarantee every toolbox is available or other readiness checks pass.
• Documents deferred discovery failures, consent requirements, and cancellation propagation.
• Clarifies endpoint fallback, pending startup status, and the currently unused unhealthy state.

File	Description
dotnet/​src/​Microsoft.Agents.AI.Foundry.Hosting/​ServiceCollectionExtensions.cs	Clarifies registration documentation for endpoint resolution and readiness behavior.
dotnet/​src/​Microsoft.Agents.AI.Foundry.Hosting/​FoundryToolboxStartupStatus.cs	Corrects enum documentation for startup outcomes and health-check mapping.
dotnet/​src/​Microsoft.Agents.AI.Foundry.Hosting/​FoundryToolboxService.cs	Documents deferred failures, cancellation, and startup status semantics.
dotnet/​src/​Microsoft.Agents.AI.Foundry.Hosting/​FoundryToolboxHealthCheck.cs	Clarifies that the check reflects startup status rather than toolbox usability.

_{Review effort: Balanced}

[github-actions]

MAF Automated Review — Iteration 1

Result: No findings
Scope: full PR (1 commit(s)): 34ee7d9df969
Model: gpt-5.6-sol

Overview

This documentation-only change largely matches the existing startup, deferred-discovery, and health-check behavior. The implementation and tests confirm that pending startup uses the configured failure status while no-endpoint, consent-required, and deferred-discovery states remain healthy, and that non-cancellation discovery failures are retried per request. No Critical, High, or Medium issue was established.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
No publishable findings remained after source verification for this scope.

[github-code-quality]

Code coverage overview

Languages: C#

C# / code-coverage/dotnet

main 3af8584	toolbox-readiness-do... 34ee7d9	+/-
86%	86%	0%

View coverage of the 1 most impacted file.

File	main 3af8584	toolbox-readiness-do... 34ee7d9	+/-
/home/runner/wo...SessionStore.cs	100%	56%	-44%

ℹ️ Calculations represent line coverage. Results may change as calculations are updated.