Restore opt-in structured content handling for tools

[kargnas]

Summary

• add support for an $autoStructuredOutput flag so legacy tools keep emitting raw content while opt-in classes surface structuredContent
• update the tool stub and README documentation to explain the v1.5 behaviour for new installations
• cover both code paths with dedicated fixtures and Pest tests

Testing

• vendor/bin/pest

---

https://chatgpt.com/codex/tasks/task_e_68eb65f926f08321af7f6405b5bfd542

[claude]

Code Review: Restore opt-in structured content handling for tools

Summary

This PR restores backward compatibility for legacy tools while introducing an opt-in mechanism for automatic structuredContent handling via the autoStructuredOutput flag. The approach is well-designed and maintains compatibility while providing a clear migration path.

Strengths

1. Excellent Backward Compatibility Strategy - Legacy tools without the flag continue working unchanged (JSON in content field), new tools can opt into modern behavior with a single property declaration, clear migration documentation in README

2. Comprehensive Test Coverage - Two dedicated test fixtures: LegacyArrayTool and AutoStructuredArrayTool, test cases cover both code paths thoroughly, tests verify exact output structure for both legacy and modern behavior

3. Documentation Quality - Clear README section explaining the opt-in mechanism (lines 805-827), code examples showing how to enable the feature, updated stub template includes the flag with helpful comments

4. Clean Implementation - Uses closure binding to access protected property (lines 70-72 in ToolsCallHandler.php), proper error handling with JsonException catching, follows existing code patterns and conventions

Issues & Concerns

1. Duplicate JSON Encoding Logic (Medium Priority) - Location: ToolsCallHandler.php:91-113. There is duplicated JSON encoding logic in two places (lines 92-98 when autoStructuredOutput is true, and lines 106-112 for legacy path). Consider refactoring to avoid duplication.

2. Property Access Pattern Inconsistency (Low Priority) - Location: ToolsCallHandler.php:68-73. The closure-based property access pattern is clever but non-standard for PHP. Consider using Reflection or adding an optional interface method instead.

3. Missing Edge Case Documentation (Low Priority) - Location: ToolsCallHandler.php:91-103. The autoStructuredOutput path assumes arrays, but behavior for non-array returns when flag is enabled is not documented. Add a comment explaining that autoStructuredOutput only affects array returns.

4. Test Coverage Gap (Low Priority) - Consider adding tests for: Tool with autoStructuredOutput = false explicitly set, non-array return types when flag is enabled, JsonException path coverage.

Security Considerations

No issues found - JSON encoding uses proper flags, error messages do not leak sensitive information, no user input is directly interpolated without validation.

Performance Considerations

Minor inefficiency: In the autoStructuredOutput = true path, JSON encoding happens only to validate, then the result is discarded. This is wasteful but unlikely to cause issues unless tools return massive payloads. Optional optimization: Cache the property_exists() and closure call results in the ToolRepository during tool registration.

Recommendations

Required before merge:

• Refactor duplicate JSON encoding logic (Issue 1)

Strongly recommended:

• Document the property access pattern choice or switch to Reflection/interface method (Issue 2)
• Add comment clarifying autoStructuredOutput only affects arrays (Issue 3)

Optional improvements:

• Add CHANGELOG entry
• Add test for explicit autoStructuredOutput = false
• Consider performance optimization for property checks

Overall Assessment

Rating: 8/10 - Well-designed solution with excellent backward compatibility strategy and comprehensive testing. The main issue is code duplication that should be addressed. Otherwise, this is a solid implementation that solves the problem elegantly. The opt-in approach is particularly smart—it allows the ecosystem to gradually adopt the new behavior without forcing breaking changes on existing tools. Great work on maintaining compatibility while moving the package forward!