[api] Document parameter_types format in ToolSpec

Per PR #670 review comment by xintongsong: spell out exactly what
strings are accepted in a Java tool's ``parameter_types`` list —
order, primitive aliases, fully-qualified reference types (boxed
primitives included), and the no-generics rule (JVM method
descriptors don't carry type parameters).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wenjin272

docs/yaml-schema.json

@@ -302,7 +302,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`` (Java method\nsignatures vary across tools).",
+      "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>``).",
       "properties": {
         "function": {
           "anyOf": [

python/flink_agents/api/yaml/specs.py

@@ -98,8 +98,21 @@ 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`` (Java method
-    signatures vary across tools).
+    ``parameter_types`` is required when ``type: java`` and is ignored
+    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
+    overloaded methods on the Java class. Each string is one of:
+
+    - A Java primitive name: one of ``boolean``, ``byte``, ``short``,
+      ``int``, ``long``, ``float``, ``double``, ``char``.
+    - A fully-qualified Java reference type (including boxed
+      primitives), e.g. ``java.lang.Double``, ``java.lang.String``,
+      ``java.util.List``.
+
+    Generic type arguments are not part of the JVM method descriptor
+    and must not be included (``java.util.List``, not
+    ``java.util.List<String>``).
     """
 
     model_config = ConfigDict(extra="forbid")