[fix] Reject parameter_types on Python YAML tools (#774)

docs/yaml-schema.json

@@ -342,7 +342,7 @@
     },
     "ToolSpec": {
       "additionalProperties": false,
-      "description": "Points ``function:`` at a callable tool.\n\n``function`` is written as ``<module-or-class>:<qualname>`` \u2014 the\ncolon separates the Python module (or Java class FQN) from the\nattribute path inside it. For Python, the right side may be a\nnested ``Class.method``.\n\n``parameter_types`` is required when ``type: java`` and is ignored\notherwise (Python tools are reflected from the callable signature).\nThe list contains one string per declared parameter of the Java\nmethod, in declaration order \u2014 the loader uses it to disambiguate\noverloaded methods on the Java class. Each string is one of:\n\n- A Java primitive name: one of ``boolean``, ``byte``, ``short``,\n  ``int``, ``long``, ``float``, ``double``, ``char``.\n- A fully-qualified Java reference type (including boxed\n  primitives), e.g. ``java.lang.Double``, ``java.lang.String``,\n  ``java.util.List``.\n\nGeneric type arguments are not part of the JVM method descriptor\nand must not be included (``java.util.List``, not\n``java.util.List<String>``).",
+      "description": "Points ``function:`` at a callable tool.\n\n``function`` is written as ``<module-or-class>:<qualname>`` \u2014 the\ncolon separates the Python module (or Java class FQN) from the\nattribute path inside it. For Python, the right side may be a\nnested ``Class.method``.\n\n``parameter_types`` is required when ``type: java`` and is forbidden\notherwise (Python tools are reflected from the callable signature).\nThe list contains one string per declared parameter of the Java\nmethod, in declaration order \u2014 the loader uses it to disambiguate\noverloaded methods on the Java class. Each string is one of:\n\n- A Java primitive name: one of ``boolean``, ``byte``, ``short``,\n  ``int``, ``long``, ``float``, ``double``, ``char``.\n- A fully-qualified Java reference type (including boxed\n  primitives), e.g. ``java.lang.Double``, ``java.lang.String``,\n  ``java.util.List``.\n\nGeneric type arguments are not part of the JVM method descriptor\nand must not be included (``java.util.List``, not\n``java.util.List<String>``).",
       "properties": {
         "function": {
           "anyOf": [

python/flink_agents/api/yaml/loader.py

@@ -179,6 +179,9 @@ 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)
+    if spec.type != "java" and spec.parameter_types is not None:
+        msg = f"Tool {spec.name!r}: 'parameter_types' is only valid for Java tools."
+        raise ValueError(msg)
     func = resolve_function(
         name=spec.name,
         function=spec.function,

python/flink_agents/api/yaml/specs.py

@@ -98,7 +98,7 @@ class ToolSpec(BaseModel):
     attribute path inside it. For Python, the right side may be a
     nested ``Class.method``.
 
-    ``parameter_types`` is required when ``type: java`` and is ignored
+    ``parameter_types`` is required when ``type: java`` and is forbidden
     otherwise (Python tools are reflected from the callable signature).
     The list contains one string per declared parameter of the Java
     method, in declaration order — the loader uses it to disambiguate

python/flink_agents/api/yaml/tests/test_loader.py

@@ -562,6 +562,30 @@ def test_build_agents_rejects_java_tool_missing_parameter_types(
         build_agents(p)
 
 
+def test_build_agents_rejects_python_tool_with_parameter_types(
+    tmp_path: Path,
+) -> None:
+    # Python tool signatures are reflected from the callable, so
+    # parameter_types is Java-only and silently dropped otherwise.
+    yaml_text = (
+        "agents:\n"
+        "  - name: a\n"
+        "    tools:\n"
+        "      - name: t1\n"
+        "        type: python\n"
+        f"        function: {_TARGETS_MODULE}:increment\n"
+        "        parameter_types: [java.lang.Integer]\n"
+        "    actions:\n"
+        "      - name: noop\n"
+        f"        function: {_TARGETS_MODULE}:increment\n"
+        "        listen_to: [input]\n"
+    )
+    p = tmp_path / "python_tool_params.yaml"
+    p.write_text(yaml_text)
+    with pytest.raises(ValueError, match="parameter_types"):
+        build_agents(p)
+
+
 def test_build_agents_builds_java_tool_descriptor(tmp_path: Path) -> None:
     """YAML parsing of a Java tool yields an api ``FunctionTool`` wrapping
     a ``JavaFunction`` descriptor — no JVM needed at parse time.