[Agent] Surface tool-argument resolution failures to the LLM

[Berenger]

Q	A
Bug fix?	yes
New feature?	no
Docs?	no
Issues	Fixes #2137
License	MIT

Problem

When ToolCallArgumentResolver::resolveArguments() fails because of invalid LLM-generated tool-call input—such as a missing mandatory parameter or a value that cannot be denormalized (for example, an invalid backed-enum value)—the exception is caught by the generic \Throwable arm in Toolbox::execute().

It is then wrapped in a ToolExecutionException, whose getToolCallResult() only returns:

An error occurred while executing tool "X".

As a result, FaultTolerantToolbox relays no actionable feedback to the model. The model cannot self-correct and typically repeats the same invalid call.

Solution

This PR treats argument-resolution failures as agent-correctable errors by reusing the existing InvalidToolCallArgumentsException.

This exception implements ToolExecutionExceptionInterface, allowing its message to reach the LLM as the tool result. This is the same mechanism already used by ValidateToolCallArgumentsListener.

• A missing mandatory parameter now throws InvalidToolCallArgumentsException with the existing message:

  Parameter "number" is mandatory for tool "tool_required_params".
  

• A denormalization failure is caught and rethrown as InvalidToolCallArgumentsException:

  Invalid value for parameter "mode" of tool "tool_with_backed_enums": The data must belong to a backed enumeration of type ...
  

  The original Serializer exception is preserved as the previous exception for debugging and logging purposes, but is not exposed directly to the LLM.

These messages are derived from the model's input and the tool's argument metadata. Exceptions raised during tool execution remain hidden and continue to produce the generic error message.

Compatibility

Code catching the component's ExceptionInterface remains unaffected, since both the old and new exceptions implement it.

Consumers catching the concrete ToolExecutionException may need to handle InvalidToolCallArgumentsException as well.

Technical Note

Toolbox::execute() now initializes $arguments before entering the try block, ensuring that it is safely available to the catch arms, as reported by PHPStan.

Tests

This behavior is covered by:

• Unit tests for the argument resolver.
• End-to-end tests through Toolbox and FaultTolerantToolbox.
• Assertions on the exact error message received by the LLM.

[chr-hertel]

Sorry for the delay @Berenger - somehow this slipped. I took care about the update and an UPGRADE.md note.

[chr-hertel]

Thank you @Berenger.