Add @tool decorator for zero-boilerplate tool definition

AGENTS.md

@@ -34,6 +34,7 @@ Use these terms consistently in code, docs, comments, and PR descriptions.
 ```text
 chainweaver/
 ├── __init__.py        Public API surface; all exports in __all__
+├── decorators.py      @tool decorator for zero-boilerplate tool definition
 ├── tools.py           Tool class: named callable with Pydantic I/O schemas
 ├── flow.py            FlowStep + Flow: ordered step definitions (Pydantic models)
 ├── registry.py        FlowRegistry: in-memory catalogue of named flows

README.md

@@ -205,13 +205,71 @@ You can also run the bundled example directly:
 python examples/simple_linear_flow.py
 ```
 
+### With the `@tool` decorator
+
+The `@tool` decorator eliminates boilerplate by introspecting type hints to
+auto-generate input schemas:
+
+```python
+from pydantic import BaseModel
+from chainweaver import tool, Flow, FlowStep, FlowRegistry, FlowExecutor
+
+class ValueOutput(BaseModel):
+    value: int
+
+class FormattedOutput(BaseModel):
+    result: str
+
+@tool(description="Doubles a number.")
+def double(number: int) -> ValueOutput:
+    return {"value": number * 2}
+
+@tool(description="Adds ten.")
+def add_ten(value: int) -> ValueOutput:
+    return {"value": value + 10}
+
+@tool(description="Formats the result.")
+def format_result(value: int) -> FormattedOutput:
+    return {"result": f"Final value: {value}"}
+
+flow = Flow(
+    name="double_add_format",
+    description="Doubles a number, adds 10, and formats the result.",
+    steps=[
+        FlowStep(tool_name="double",        input_mapping={"number": "number"}),
+        FlowStep(tool_name="add_ten",       input_mapping={"value": "value"}),
+        FlowStep(tool_name="format_result", input_mapping={"value": "value"}),
+    ],
+)
+
+registry = FlowRegistry()
+registry.register_flow(flow)
+
+executor = FlowExecutor(registry=registry)
+executor.register_tool(double)
+executor.register_tool(add_ten)
+executor.register_tool(format_result)
+
+result = executor.execute_flow("double_add_format", {"number": 5})
+print(result.final_output)  # {'number': 5, 'value': 20, 'result': 'Final value: 20'}
+```
+
+Decorated tools are also directly callable:
+
+```python
+print(double(number=5))  # {'value': 10}
+```
+
+See `examples/decorator_tool.py` for a runnable before/after comparison.
+
 ---
 
 ## Architecture
 
 ```
 chainweaver/
 ├── __init__.py       # Public API
+├── decorators.py     # @tool decorator for zero-boilerplate tool definition
 ├── tools.py          # Tool — named callable with Pydantic schemas
 ├── flow.py           # FlowStep + Flow — ordered step definitions
 ├── registry.py       # FlowRegistry — in-memory flow catalogue
@@ -346,6 +404,7 @@ All errors are typed and traceable:
 | `SchemaValidationError` | Input or output fails Pydantic validation |
 | `InputMappingError` | A mapping key is not present in the context |
 | `FlowExecutionError` | The tool callable raises an unexpected exception |
+| `ToolDefinitionError` | The `@tool` decorator cannot build a tool from a function |
 
 All exceptions inherit from `ChainWeaverError`.
 

chainweaver/__init__.py

@@ -14,20 +14,23 @@
         SchemaValidationError,
         InputMappingError,
         FlowExecutionError,
+        ToolDefinitionError,
     )
 """
 
 from __future__ import annotations
 
 import logging
 
+from chainweaver.decorators import tool
 from chainweaver.exceptions import (
     ChainWeaverError,
     FlowAlreadyExistsError,
     FlowExecutionError,
     FlowNotFoundError,
     InputMappingError,
     SchemaValidationError,
+    ToolDefinitionError,
     ToolNotFoundError,
 )
 from chainweaver.executor import ExecutionResult, FlowExecutor, StepRecord
@@ -55,5 +58,7 @@
     "SchemaValidationError",
     "StepRecord",
     "Tool",
+    "ToolDefinitionError",
     "ToolNotFoundError",
+    "tool",
 ]

chainweaver/decorators.py

@@ -0,0 +1,208 @@
+"""Decorator for zero-boilerplate tool definition.
+
+The :func:`tool` decorator creates a :class:`~chainweaver.tools.Tool` from a
+type-annotated Python function, eliminating the need to manually define
+Pydantic input/output schemas and the ``Tool()`` constructor call.
+
+Example::
+
+    from chainweaver import tool
+
+    class ValueOutput(BaseModel):
+        value: int
+
+    @tool(description="Doubles a number.")
+    def double(number: int) -> ValueOutput:
+        return {"value": number * 2}
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any, get_type_hints, overload
+
+from pydantic import BaseModel, create_model
+
+from chainweaver.exceptions import ToolDefinitionError
+from chainweaver.tools import Tool
+
+
+class _DecoratedTool(Tool):
+    """A Tool created via the ``@tool`` decorator that is also directly callable.
+
+    Behaves exactly like a :class:`~chainweaver.tools.Tool` but additionally
+    supports calling with the original function signature.
+    """
+
+    def __init__(
+        self,
+        *,
+        original_fn: Callable[..., Any],
+        name: str,
+        description: str,
+        input_schema: type[BaseModel],
+        output_schema: type[BaseModel],
+        fn: Callable[[Any], dict[str, Any]],
+    ) -> None:
+        super().__init__(
+            name=name,
+            description=description,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            fn=fn,
+        )
+        self._original_fn = original_fn
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the original function directly, bypassing schema validation."""
+        return self._original_fn(*args, **kwargs)
+
+
+def _build_tool(
+    fn: Callable[..., Any],
+    *,
+    name: str | None,
+    description: str | None,
+) -> _DecoratedTool:
+    """Build a :class:`_DecoratedTool` from a type-annotated function."""
+    tool_name = name if name is not None else fn.__name__
+    tool_description = description if description is not None else (fn.__doc__ or "").strip()
+
+    try:
+        hints = get_type_hints(fn, include_extras=True)
+    except (NameError, TypeError) as exc:
+        raise ToolDefinitionError(
+            fn.__name__,
+            f"Failed to resolve type hints: {exc}. "
+            f"Ensure all annotations are importable and any forward references "
+            f"are either quoted or resolvable in the tool's module.",
+        ) from exc
+    sig = inspect.signature(fn)
+
+    # -- Validate return type -----------------------------------------------
+    return_type = hints.get("return")
+    if return_type is None:
+        raise ToolDefinitionError(
+            fn.__name__,
+            "Missing a return type annotation. "
+            "The return type must be a BaseModel subclass. "
+            "Use the explicit Tool() constructor for functions without full type hints.",
+        )
+
+    if not (isinstance(return_type, type) and issubclass(return_type, BaseModel)):
+        raise ToolDefinitionError(
+            fn.__name__,
+            f"Return type must be a BaseModel subclass, got '{return_type}'. "
+            f"Use the explicit Tool() constructor for functions without full type hints.",
+        )
+
+    output_schema = return_type
+
+    # -- Build input schema fields ------------------------------------------
+    fields: dict[str, Any] = {}
+    for param_name, param in sig.parameters.items():
+        # Positional-only parameters cannot be passed as keyword arguments,
+        # but the adapter always calls the function via **kwargs.
+        if param.kind is inspect.Parameter.POSITIONAL_ONLY:
+            raise ToolDefinitionError(
+                fn.__name__,
+                "Uses positional-only parameters, "
+                "which are not supported by the @tool decorator. "
+                "Use the explicit Tool() constructor instead.",
+            )
+
+        if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
+            raise ToolDefinitionError(
+                fn.__name__,
+                "Uses *args or **kwargs, "
+                "which cannot be introspected into a schema. "
+                "Use the explicit Tool() constructor instead.",
+            )
+
+        if param_name not in hints:
+            raise ToolDefinitionError(
+                fn.__name__,
+                f"Parameter '{param_name}' is missing a type annotation. "
+                f"Use the explicit Tool() constructor for functions "
+                f"without full type hints.",
+            )
+
+        param_type = hints[param_name]
+        if param.default is inspect.Parameter.empty:
+            fields[param_name] = (param_type, ...)
+        else:
+            fields[param_name] = (param_type, param.default)
+
+    input_schema: type[BaseModel] = create_model(f"{tool_name}_input", **fields)
+
+    # -- Create adapter for Tool.fn signature --------------------------------
+    def _adapter(inp: Any) -> dict[str, Any]:
+        return fn(**inp.model_dump())  # type: ignore[no-any-return]
+
+    return _DecoratedTool(
+        original_fn=fn,
+        name=tool_name,
+        description=tool_description,
+        input_schema=input_schema,
+        output_schema=output_schema,
+        fn=_adapter,
+    )
+
+
+@overload
+def tool(fn: Callable[..., Any], /) -> _DecoratedTool: ...
+
+
+@overload
+def tool(
+    *,
+    name: str | None = ...,
+    description: str | None = ...,
+) -> Callable[[Callable[..., Any]], _DecoratedTool]: ...
+
+
+def tool(
+    fn: Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> _DecoratedTool | Callable[[Callable[..., Any]], _DecoratedTool]:
+    """Create a :class:`~chainweaver.tools.Tool` from a type-annotated function.
+
+    Can be used as a bare decorator or as a decorator factory with keyword
+    arguments:
+
+    .. code-block:: python
+
+        @tool
+        def greet(name: str) -> GreetOutput:
+            \"\"\"Say hello.\"\"\"
+            return {"message": f"Hello, {name}!"}
+
+        @tool(name="custom_double", description="Doubles a number.")
+        def double(number: int) -> ValueOutput:
+            return {"value": number * 2}
+
+    Args:
+        fn: The function to wrap (used when the decorator is applied without
+            parentheses).
+        name: Override the tool name.  Defaults to the function name.
+        description: Tool description.  Falls back to the function's docstring
+            if not provided.
+
+    Returns:
+        A :class:`~chainweaver.tools.Tool` that is also directly callable with
+        the original function's signature.
+
+    Raises:
+        ToolDefinitionError: When type hints are missing or the return type is
+            not a :class:`~pydantic.BaseModel` subclass.
+    """
+    if fn is not None:
+        return _build_tool(fn, name=name, description=description)
+
+    def _decorator(fn: Callable[..., Any]) -> _DecoratedTool:
+        return _build_tool(fn, name=name, description=description)
+
+    return _decorator

chainweaver/exceptions.py

@@ -71,3 +71,12 @@ def __init__(self, tool_name: str, step_index: int, detail: str) -> None:
         self.step_index = step_index
         self.detail = detail
         super().__init__(f"Execution error in tool '{tool_name}' at step {step_index}: {detail}")
+
+
+class ToolDefinitionError(ChainWeaverError):
+    """Raised when the ``@tool`` decorator cannot build a tool from a function."""
+
+    def __init__(self, function_name: str, detail: str) -> None:
+        self.function_name = function_name
+        self.detail = detail
+        super().__init__(f"Cannot define tool from function '{function_name}': {detail}")

docs/agent-context/architecture.md

@@ -21,6 +21,7 @@ and tools, the same flow produces the same output every time.
 
 | Module | Responsibility | Key constraint |
 |--------|---------------|----------------|
+| `decorators.py` | `@tool` decorator for zero-boilerplate tool definition | Returns a `Tool` subclass; introspects type hints |
 | `tools.py` | Define `Tool`: name + callable + Pydantic I/O schemas | Tool functions must be `fn(BaseModel) -> dict[str, Any]` |
 | `flow.py` | Define `FlowStep` and `Flow` as Pydantic models | Pure data definitions; no execution logic |
 | `registry.py` | Store and retrieve flows by name | In-memory; intentionally simple for later wrapping |