Add EnrichParameter to document tool params (#113)

Author: simba-git

README.md

@@ -382,6 +382,20 @@ async def get_customer(cid: int, ctx: EnrichContext) -> Customer:
     return await ctx.cache.get_or_set(f"customer:{cid}", fetch)
 ```
 
+### 🧭 Parameter Hints
+
+Provide examples and metadata for tool parameters using `EnrichParameter`:
+
+```python
+from enrichmcp import EnrichParameter
+
+@app.retrieve
+async def greet_user(name: str = EnrichParameter(description="user name", examples=["bob"])) -> str:
+    return f"Hello {name}"
+```
+
+Tool descriptions will include the parameter type, description, and examples.
+
 ### 🌐 HTTP & SSE Support
 
 Serve your API over standard output (default), SSE, or HTTP:

docs/api.md

@@ -41,6 +41,9 @@ class User(EnrichModel):
 ### [EnrichContext](api/context.md)
 Context object with request scoped utilities including caching.
 
+### [EnrichParameter](api/parameter.md)
+Attach metadata like descriptions and examples to function parameters.
+
 ### [Cache](api/cache.md)
 Request, user, and global scoped caching utilities.
 

docs/api/parameter.md

@@ -0,0 +1,14 @@
+# Parameter Metadata
+
+`EnrichParameter` attaches hints like descriptions and examples to function parameters.
+When a parameter's default value is an instance of `EnrichParameter`, those hints
+are appended to the generated tool description (except for parameters typed as
+`EnrichContext`).
+
+```python
+from enrichmcp import EnrichParameter
+
+@app.retrieve
+async def greet(name: str = EnrichParameter(description="user name", examples=["bob"])) -> str:
+    return f"Hello {name}"
+```

docs/getting-started.md

@@ -191,6 +191,20 @@ async def get_user(user_id: int, ctx: EnrichContext) -> User:
 
 Context is automatically injected when you add a parameter typed as `EnrichContext`.
 
+## Parameter Hints
+
+You can attach descriptions and examples to resource parameters using `EnrichParameter`:
+
+```python
+from enrichmcp import EnrichParameter
+
+@app.retrieve
+async def greet(name: str = EnrichParameter(description="user name", examples=["bob"])) -> str:
+    return f"Hello {name}"
+```
+
+These hints are appended to the generated tool description so agents know how to call the resource.
+
 ## Using Existing SQLAlchemy Models
 
 Have a project full of SQLAlchemy models already? You can expose them as an MCP

src/enrichmcp/__init__.py

@@ -30,6 +30,7 @@
 from .entity import EnrichModel
 from .lifespan import combine_lifespans
 from .pagination import CursorParams, CursorResult, PageResult, PaginatedResult, PaginationParams
+from .parameter import EnrichParameter
 from .relationship import (
     Relationship,
 )
@@ -52,6 +53,7 @@
     "EnrichContext",
     "EnrichMCP",
     "EnrichModel",
+    "EnrichParameter",
     "MemoryCache",
     "PageResult",
     "PaginatedResult",

src/enrichmcp/app.py

@@ -4,6 +4,7 @@
 Provides the EnrichMCP class for creating MCP applications.
 """
 
+import inspect
 import warnings
 from collections.abc import Callable
 from typing import (
@@ -24,6 +25,7 @@
 from .cache import CacheBackend, ContextCache, MemoryCache
 from .context import EnrichContext
 from .entity import EnrichModel
+from .parameter import EnrichParameter
 from .relationship import Relationship
 
 # Type variables
@@ -320,6 +322,52 @@ def describe_model(self) -> str:
 
         return "\n".join(lines)
 
+    def _append_enrichparameter_hints(self, description: str, fn: Callable[..., Any]) -> str:
+        """Append ``EnrichParameter`` metadata to a description string."""
+
+        hints: list[str] = []
+        try:
+            sig = inspect.signature(fn)
+        except (TypeError, ValueError):  # pragma: no cover - defensive
+            return description
+
+        for param in sig.parameters.values():
+            default = param.default
+            annotation = param.annotation
+
+            if isinstance(default, EnrichParameter):
+                if annotation is EnrichContext:
+                    # Context parameters are stripped from the final tool
+                    # interface so hints would be confusing to the agent.
+                    continue
+
+                param_type = "Any"
+                if annotation is not inspect.Parameter.empty:
+                    if get_origin(annotation) is Literal:
+                        values = ", ".join(repr(v) for v in get_args(annotation))
+                        param_type = f"Literal[{values}]"
+                    else:
+                        param_type = getattr(annotation, "__name__", str(annotation))
+
+                parts = [param_type]
+                if default.description:
+                    parts.append(default.description)
+                if default.examples:
+                    joined = ", ".join(map(str, default.examples))
+                    parts.append(f"examples: {joined}")
+                if default.metadata:
+                    meta = ", ".join(f"{k}: {v}" for k, v in default.metadata.items())
+                    parts.append(meta)
+
+                hints.append(f"{param.name} - {'; '.join(parts)}")
+
+        if hints:
+            description = (
+                description.rstrip() + "\n\nParameter hints:\n" + "\n".join(f"- {h}" for h in hints)
+            )
+
+        return description
+
     def retrieve(
         self,
         func: Callable[..., Any] | None = None,
@@ -369,6 +417,9 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
             if resource_desc == fn.__doc__ and resource_desc:
                 resource_desc = resource_desc.strip()
 
+            # Append EnrichParameter parameter hints
+            resource_desc = self._append_enrichparameter_hints(resource_desc, fn)
+
             # Store the resource for testing
             self.resources[resource_name] = fn
             # Create and apply the MCP tool decorator

src/enrichmcp/parameter.py

@@ -0,0 +1,29 @@
+"""Utility for annotating function parameters with extra metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - import for type hints
+    from collections.abc import Iterable
+
+
+@dataclass
+class EnrichParameter:
+    """Metadata container for function parameters.
+
+    When a parameter's default value is an instance of ``EnrichParameter`` the
+    metadata contained here is appended to the generated tool description. The
+    ``default`` attribute is **not** used as the runtime default value; it simply
+    provides a placeholder so function signatures remain valid.
+    """
+
+    default: Any | None = None
+    description: str | None = None
+    examples: Iterable[Any] | None = None
+    metadata: dict[str, Any] = dataclass_field(default_factory=dict)
+
+    def __iter__(self) -> Iterable[Any]:  # pragma: no cover - convenience
+        yield self.default

tests/test_enrichparameter.py

@@ -0,0 +1,25 @@
+from unittest.mock import patch
+
+import pytest
+
+from enrichmcp import EnrichContext, EnrichMCP, EnrichParameter
+
+
+@pytest.mark.asyncio
+async def test_enrichparameter_hints_appended():
+    app = EnrichMCP("Test", description="desc")
+    with patch.object(app.mcp, "tool", wraps=app.mcp.tool) as mock_tool:
+
+        @app.retrieve(description="Base desc")
+        async def my_resource(
+            ctx: EnrichContext,
+            name: str = EnrichParameter(description="user name", examples=["bob"]),
+        ) -> dict:
+            return {}
+
+    desc = mock_tool.call_args.kwargs["description"]
+    assert "Parameter hints:" in desc
+    assert "name - str" in desc
+    assert "user name" in desc
+    assert "examples: bob" in desc
+    assert "ctx" not in desc