[Bug] YAML loader silently accepts parameter_types on Python tools

[Sxnan]

Search before asking

• I searched in the issues and found nothing similar.

Description

Found during YAML doc verification (#742).

docs/content/docs/development/yaml.md line 137 documents parameter_types
as "java only" and Forbidden for Python tools:

Field	Required	Description
parameter_types	java only	Required for Java tools — one Java type FQN per declared parameter, in order. Forbidden for Python tools (the signature is reflected from the callable).

The Python loader does not enforce the prohibition. In
python/flink_agents/api/yaml/loader.py:178-188:

def _build_tool(spec: ToolSpec) -> FunctionTool:
    if spec.type == "java" and spec.parameter_types is None:
        msg = f"Tool {spec.name!r}: java tools must declare 'parameter_types' in YAML."
        raise ValueError(msg)
    func = resolve_function(
        name=spec.name,
        function=spec.function,
        language=spec.type,
        parameter_types=spec.parameter_types,
    )
    return FunctionTool(func=func)

Only the missing-on-Java direction is checked. When type is python (or
unset) and parameter_types is set, the value passes through to
resolve_function, which discards it in the Python branch:

return PythonFunction(module=left, qualname=right)   # parameter_types not used

ActionSpec handles the analogous case correctly by not declaring
parameter_types at all (combined with extra="forbid"), and
test_action_spec_rejects_parameter_types verifies that. ToolSpec declares
the field, so the same approach does not work without a custom validator.

How to reproduce

agents:
  - name: a
    tools:
      - name: my_py_tool
        type: python
        function: my_pkg.tools:add
        parameter_types: [java.lang.Integer, java.lang.Integer]   # doc: "Forbidden"
    actions:
      - name: act
        function: my_pkg.actions:process_input
        listen_to: [input]

env = AgentsExecutionEnvironment.get_execution_environment()
env.load_yaml("repro.yaml")   # succeeds; parameter_types silently dropped

Fix

Either (preferred — matches the doc):

def _build_tool(spec: ToolSpec) -> FunctionTool:
    if spec.type == "java" and spec.parameter_types is None:
        raise ValueError(...)
    if spec.type != "java" and spec.parameter_types is not None:
        raise ValueError(
            f"Tool {spec.name!r}: 'parameter_types' is only valid for Java tools."
        )
    ...

Or relax the doc to "Ignored for Python tools" instead of "Forbidden".

Version and environment

Flink Agents 0.3.0 (main). Python loader only; Java loader unverified.

Are you willing to submit a PR?

• I'm willing to submit a PR!