[LI (ktz03)]

Motivation & Context

The add_usage_details docstring says a key is skipped when either value is not an integer. Its existing implementation instead treats None as zero, and the public UsageDetails fields allow int | None. For example, merging an input count of None with 3 returns 3; the current wording incorrectly suggests that key is skipped.

Description & Review Guide

• What are the major changes? Clarify that missing keys and None contribute zero, other non-integer values cause the key to be skipped, and booleans are skipped.
• What is the impact of these changes? Documentation only. Runtime behavior, signatures and return types are unchanged.
• What do you want reviewers to focus on? Consistency of this paragraph with the existing optional fields and the helper's value checks.

Validation: four ordinary integer/optional/missing-key inputs passed against the exact extracted complete helper and real UsageDetails definition both before and after the documentation change. Input dictionaries were preserved. Whole-file ASTs are identical after removing docstrings, and both versions parse with Python 3.10 syntax. Ruff 0.17.1 single-file lint and format checks passed using the current repository configuration and the unchanged package marker. The initial missing-package-marker INP001 diagnostic was retained locally; supplying the real unchanged marker resolved the frozen-layout issue without disabling a rule.

These are local Windows checks with an existing interpreter and dependency set. Full SDK import, provider calls, services, package builds, the full test suite and official CI were not run. The existing runtime already handles these inputs correctly.

Related Issue

N/A - trivial change. This is an obvious correction of existing documentation to match the already-implemented handling of optional values and booleans. It introduces no behavior or design change. A search for an open PR covering add_usage_details and None found none.

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: AI assisted the documentation correction, source comparison, local validation and this PR description. The accountable human has reviewed this contribution and its validation materials. No personal execution of the automated checks is claimed.

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.

[Copilot]

🟢 Approval recommended

No active review issues were identified for this documentation-only clarification of optional usage-counter handling.

No open issues 🎉

What changed in this PR

This documentation-only PR clarifies how add_usage_details handles optional usage counters in the Python SDK. Runtime behavior, signatures, and return types remain unchanged.

Changes:

• Documents that missing keys and None values contribute zero.
• Clarifies that other non-integer values, including booleans, cause the key to be skipped.

File	Description
python/​packages/​core/​agent_framework/​_types.py	Updates the add_usage_details docstring to describe existing value handling.

_{Review effort: Balanced}