fix(toolbox-core): Use typing.Annotated for reliable parameter descriptions instead of docstrings (#371)

* fix(toolbox-core): Use typing.Annotated for reliable parameter descriptions instead of docstrings

# Overview

This PR refactors how `toolbox-core` handles tool parameter descriptions, moving them from dynamically generated docstrings directly into the function signature itself using `typing.Annotated`.

# Problem

Previously, our approach involved using the `create_func_docstring` utility to dynamically build a Google-style `Args:` section within the ToolboxTool function's docstring. This method was unreliable and required custom logic just to format correctly (#369).

We found this approach to be extremely flaky, as it depended entirely on downstream orchestrators (like LangChain and LlamaIndex) to successfully parse that specific docstring format. This led to bugs, such as orchestrations showing parameter descriptions twice, or (as seen specifically with LlamaIndex) failing to parse the descriptions at all.

# Solution

This PR implements a much cleaner and more reliable solution. We now modify ParameterSchema.__get_type (in protocol.py) to wrap the base Python type directly with typing.Annotated, passing the parameter description as the second argument.

For example, a parameter signature that was previously just:
```py
param1: str (with the description hidden in the docstring)
```

...is now natively represented in the signature as:
```py
param1: Annotated[str, "The description of param1"]
```

This is the standard, modern Python way to attach metadata to types. Frameworks like LlamaIndex and LangChain (via Pydantic) are built to introspect Annotated natively, ensuring descriptions are picked up reliably without buggy docstring parsing.

As an added benefit, this simplifies the codebase significantly, allowing us to remove the custom create_func_docstring utility and all of its associated test cases.

> [!NOTE]
> This feature is available as our minimum supported version is Python 3.9, where `Annotated` was introduced ([PEP 593](https://peps.python.org/pep-0593/)).

* chore: delint

* chore: Fix unit test case

* chore: Fix integration tests

* chore: Delint

* chore: Fix integration tests

* chore: Fix integration tests

* chore: Fix unit test case

* chore: Update internal method name

Author: anubhav756

packages/toolbox-core/src/toolbox_core/protocol.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 from inspect import Parameter
-from typing import Any, Optional, Type, Union
+from typing import Annotated, Any, Optional, Type, Union
 
 from pydantic import BaseModel
 
@@ -60,12 +60,12 @@ class ParameterSchema(BaseModel):
     items: Optional["ParameterSchema"] = None
     additionalProperties: Optional[Union[bool, AdditionalPropertiesSchema]] = None
 
-    def __get_type(self) -> Type:
-        base_type: Type
+    def __get_annotation(self) -> Any:
+        base_type: Any
         if self.type == "array":
             if self.items is None:
                 raise ValueError("Unexpected value: type is 'array' but items is None")
-            base_type = list[self.items.__get_type()]  # type: ignore
+            base_type = list[self.items.__get_annotation()]  # type: ignore
         elif self.type == "object":
             if isinstance(self.additionalProperties, AdditionalPropertiesSchema):
                 value_type = self.additionalProperties.get_value_type()
@@ -76,15 +76,15 @@ def __get_type(self) -> Type:
             base_type = _get_python_type(self.type)
 
         if not self.required:
-            return Optional[base_type]  # type: ignore
+            base_type = Optional[base_type]
 
-        return base_type
+        return Annotated[base_type, self.description]
 
     def to_param(self) -> Parameter:
         return Parameter(
             self.name,
             Parameter.POSITIONAL_OR_KEYWORD,
-            annotation=self.__get_type(),
+            annotation=self.__get_annotation(),
             default=Parameter.empty if self.required else None,
         )
 

packages/toolbox-core/src/toolbox_core/tool.py

@@ -24,7 +24,6 @@
 
 from .protocol import ParameterSchema
 from .utils import (
-    create_func_docstring,
     identify_auth_requirements,
     params_to_pydantic_model,
     resolve_value,
@@ -101,7 +100,7 @@ def __init__(
 
         # the following properties are set to help anyone that might inspect it determine usage
         self.__name__ = name
-        self.__doc__ = create_func_docstring(self.__description, self.__params)
+        self.__doc__ = self.__description
         self.__signature__ = Signature(
             parameters=inspect_type_params, return_annotation=str
         )

packages/toolbox-core/src/toolbox_core/utils.py

@@ -31,18 +31,6 @@
 from toolbox_core.protocol import ParameterSchema
 
 
-def create_func_docstring(description: str, params: Sequence[ParameterSchema]) -> str:
-    """Convert tool description and params into its function docstring"""
-    docstring = description
-    if not params:
-        return docstring
-    docstring += "\n\nArgs:"
-    for p in params:
-        annotation = p.to_param().annotation
-        docstring += f"\n    {p.name} ({getattr(annotation, '__name__', str(annotation))}): {p.description}"
-    return docstring
-
-
 def identify_auth_requirements(
     req_authn_params: Mapping[str, list[str]],
     req_authz_tokens: Sequence[str],

packages/toolbox-core/tests/test_client.py

@@ -15,7 +15,7 @@
 
 import inspect
 import json
-from typing import Any, Callable, Mapping, Optional
+from typing import Annotated, Any, Callable, Mapping, Optional, get_args, get_origin
 from unittest.mock import AsyncMock, Mock
 
 import pytest
@@ -192,15 +192,30 @@ async def test_load_tool_success(aioresponses, test_tool_str):
         assert callable(loaded_tool)
         # Assert introspection attributes are set correctly
         assert loaded_tool.__name__ == TOOL_NAME
-        expected_description = (
-            test_tool_str.description
-            + f"\n\nArgs:\n    param1 (str): Description of Param1"
-        )
+        expected_description = test_tool_str.description
         assert loaded_tool.__doc__ == expected_description
 
-        # Assert signature inspection
+        # Assert signature inspection, including annotated descriptions
         sig = inspect.signature(loaded_tool)
-        assert list(sig.parameters.keys()) == [p.name for p in test_tool_str.parameters]
+        actual_params_map = sig.parameters
+        expected_params_list = test_tool_str.parameters
+
+        assert len(actual_params_map) == len(expected_params_list)
+
+        for expected_param_schema in expected_params_list:
+            param_name = expected_param_schema.name
+            assert param_name in actual_params_map
+            actual_param = actual_params_map[param_name]
+            annotation = actual_param.annotation
+            assert get_origin(annotation) is Annotated
+            annotation_args = get_args(annotation)
+            actual_param_description = annotation_args[1]
+            assert actual_param_description == expected_param_schema.description
+
+            if expected_param_schema.required:
+                assert actual_param.default is inspect.Parameter.empty
+            else:
+                assert actual_param.default is None
 
         assert await loaded_tool("some value") == "ok"
 

packages/toolbox-core/tests/test_e2e.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 from inspect import Parameter, signature
-from typing import Any, Optional
+from typing import Annotated, Any, Optional
 
 import pytest
 import pytest_asyncio
@@ -243,15 +243,24 @@ async def test_tool_signature_is_correct(self, toolbox: ToolboxClient):
 
         # The required parameter should have no default
         assert sig.parameters["email"].default is Parameter.empty
-        assert sig.parameters["email"].annotation is str
+        assert (
+            sig.parameters["email"].annotation
+            is Annotated[str, "The email to search for."]
+        )
 
         # The optional parameter should have a default of None
         assert sig.parameters["data"].default is None
-        assert sig.parameters["data"].annotation is Optional[str]
+        assert (
+            sig.parameters["data"].annotation
+            is Annotated[Optional[str], "The row to narrow down the search."]
+        )
 
         # The optional parameter should have a default of None
         assert sig.parameters["id"].default is None
-        assert sig.parameters["id"].annotation is Optional[int]
+        assert (
+            sig.parameters["id"].annotation
+            is Annotated[Optional[int], "The id to narrow down the search."]
+        )
 
     async def test_run_tool_with_optional_params_omitted(self, toolbox: ToolboxClient):
         """Invoke a tool providing only the required parameter."""
@@ -395,15 +404,27 @@ async def test_tool_signature_with_map_params(self, toolbox: ToolboxClient):
         sig = signature(tool)
 
         assert "execution_context" in sig.parameters
-        assert sig.parameters["execution_context"].annotation == dict[str, Any]
+        assert (
+            sig.parameters["execution_context"].annotation
+            == Annotated[
+                dict[str, Any],
+                "A flexible set of key-value pairs for the execution environment.",
+            ]
+        )
         assert sig.parameters["execution_context"].default is Parameter.empty
 
         assert "user_scores" in sig.parameters
-        assert sig.parameters["user_scores"].annotation == dict[str, int]
+        assert (
+            sig.parameters["user_scores"].annotation
+            == Annotated[dict[str, int], "A map of user IDs to their scores."]
+        )
         assert sig.parameters["user_scores"].default is Parameter.empty
 
         assert "feature_flags" in sig.parameters
-        assert sig.parameters["feature_flags"].annotation == Optional[dict[str, bool]]
+        assert (
+            sig.parameters["feature_flags"].annotation
+            == Annotated[Optional[dict[str, bool]], "Optional feature flags."]
+        )
         assert sig.parameters["feature_flags"].default is None
 
     async def test_run_tool_with_map_params(self, toolbox: ToolboxClient):