[imorland]

Preserve explicit JSON null in structured tool results while keeping omitted content absent through construction, helper factories and decoding. Apply the distinction to modern server wrapping and output validation, with legacy automatic wrapping unchanged.

Fixes #673 (Explicit structuredContent: null is omitted from tool results).

[Copilot]

🟢 Approval recommended

No active review issues remain for the changes distinguishing omitted structured content from explicit JSON null.

No open issues 🎉

What changed in this PR

Addresses #673 by distinguishing omitted structured content from explicit JSON null in the PHP SDK’s tool results, while preserving legacy automatic wrapping behavior.

Changes:

• Adds an absence sentinel and hasStructuredContent() to preserve null through construction, serialization, and decoding.
• Updates modern server wrapping and output-schema validation to handle explicit null.
• Adds regression coverage and documents the behavior and compatibility changes.

File	Description
tests/​Unit/​Server/​Handler/​Request/​CallToolHandlerTest.php	Distinguishes legacy warnings for explicit null and omitted content.
tests/​Unit/​Schema/​Result/​CallToolResultTest.php	Covers omission, explicit null, helper factories, and round trips.
tests/​Integration/​StructuredNullTest.php	Covers null wrapping, validation, and client decoding across protocol eras.
tests/​Integration/​Fixture/​structured_null.php	Provides tools returning absent, explicit, serialized, and invalid null results.
src/​Server/​Handler/​Request/​CallToolHandler.php	Preserves modern null results and validates present structured content.
src/​Schema/​Result/​CallToolResult.php	Tracks structured-content presence separately from its value.
src/​Schema/​Enum/​UndefinedValue.php	Introduces the sentinel for omitted structured content.
docs/​servers/​tools.md	Explains null handling and migration from null-as-omission.
CHANGELOG.md	Records server behavior and the schema compatibility break.

_{Review effort: Balanced}