misc

src/wf_core/models/steps.py

@@ -14,8 +14,19 @@ class InputPathBinding(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    target: LocalPath
-    path: GraphSourcePath
+    target: LocalPath = Field(
+        description=(
+            "Node-local input path to populate. Use {'root': 'local', "
+            "'parts': ['field']} or {'root': 'local', 'parts': []} for the "
+            "whole node input payload."
+        )
+    )
+    path: GraphSourcePath = Field(
+        description=(
+            "Workflow source path to read from input, state, or context. "
+            "Example: {'root': 'input', 'parts': ['text']}."
+        )
+    )
 
 
 class InputValueBinding(BaseModel):
@@ -23,13 +34,26 @@ class InputValueBinding(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    target: LocalPath
-    value: object
+    target: LocalPath = Field(
+        description="Node-local input path that receives this literal JSON value."
+    )
+    value: object = Field(
+        description=(
+            "Literal JSON-compatible value to pass to the node. Use this for "
+            "constants, not for values read from workflow input or state."
+        )
+    )
 
 
 InputBinding = Annotated[
     InputPathBinding | InputValueBinding,
-    Field(union_mode="left_to_right"),
+    Field(
+        union_mode="left_to_right",
+        description=(
+            "Canonical node input binding. Use either a path binding with "
+            "`path`, or a literal binding with `value`; do not provide both."
+        ),
+    ),
 ]
 """Canonical node input binding, distinguished by `path` vs `value` shape."""
 
@@ -39,8 +63,18 @@ class OutputBinding(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    source: LocalPath
-    target: StatePath
+    source: LocalPath = Field(
+        description=(
+            "Node-local output path to read. Use {'root': 'local', 'parts': []} "
+            "to write the whole node output payload."
+        )
+    )
+    target: StatePath = Field(
+        description=(
+            "Writable workflow state path. Bare state is invalid; use a field "
+            "path such as {'root': 'state', 'parts': ['echoed']}."
+        )
+    )
 
 
 class NodeUse(BaseModel):
@@ -50,8 +84,20 @@ class NodeUse(BaseModel):
     type: Literal["node"]
     node: str
     desc: str | None = None
-    input: list[InputBinding] = Field(default_factory=list)
-    output: list[OutputBinding] = Field(default_factory=list)
+    input: list[InputBinding] = Field(
+        default_factory=list,
+        description=(
+            "Bindings that build the node-local input payload from workflow "
+            "input/state/context paths or literal values."
+        ),
+    )
+    output: list[OutputBinding] = Field(
+        default_factory=list,
+        description=(
+            "Bindings that commit node-local output fields into workflow state "
+            "after the node returns successfully."
+        ),
+    )
     retry: int | None = Field(default=None, ge=0)
     timeout_seconds: int | None = Field(default=None, gt=0)
 
@@ -124,8 +170,10 @@ class ForeachNode(BaseModel):
 
     id: str
     type: Literal["foreach"]
-    over: GraphSourcePath
-    as_: str = Field(alias="as")
+    over: GraphSourcePath = Field(
+        description="Workflow input/state/context path that must resolve to a list."
+    )
+    as_: str = Field(alias="as", description="Context key for the current item.")
     mode: Literal["serial", "parallel"] = "serial"
     on_item_error: Literal["fail", "collect", "skip"] = "fail"
 
@@ -143,8 +191,18 @@ class InterruptNode(BaseModel):
     id: str
     type: Literal["interrupt"]
     kind: str
-    request: list[InputBinding] = Field(default_factory=list)
-    resume: list[OutputBinding] = Field(default_factory=list)
+    request: list[InputBinding] = Field(
+        default_factory=list,
+        description=(
+            "Bindings that build the interrupt request payload sent to the client."
+        ),
+    )
+    resume: list[OutputBinding] = Field(
+        default_factory=list,
+        description=(
+            "Bindings that commit resume payload fields back into workflow state."
+        ),
+    )
     outcomes: list[str] = Field(default_factory=lambda: ["submitted"])
 
     @model_validator(mode="before")

src/wf_mcp/admin_surface/handlers/transparent.py

@@ -97,13 +97,13 @@ class TransparentAdminHandlers:
 
     def enable_connection(self, connection_id: str) -> dict[str, Any]:
         return self.runtime.require_manager().set_connection_enabled(
-            connection_id,
+            connection_id=connection_id,
             enabled=True,
         )
 
     def disable_connection(self, connection_id: str) -> dict[str, Any]:
         return self.runtime.require_manager().set_connection_enabled(
-            connection_id,
+            connection_id=connection_id,
             enabled=False,
         )
 

src/wf_mcp/workflow_surface/tools.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from typing import Any, Mapping
+from typing import Annotated, Any, Mapping
 
 from fastmcp import FastMCP
+from pydantic import Field
 
 from wf_artifacts import ArtifactKind
 from wf_artifacts.models import RequiredCapability
@@ -546,7 +547,16 @@ def register_workflow_tools(server: FastMCP[Any], service: WfMcpService) -> None
     async def run_deployment(
         deployment_id: str,
         workflow_input: dict[str, Any],
-        trace_range: TraceRange | None = None,
+        trace_range: Annotated[
+            TraceRange | None,
+            Field(
+                description=(
+                    "Debug traces range to return. Omit for normal compact runs; "
+                    "trace entries can include resolved inputs, outputs, and "
+                    "state changes."
+                )
+            ),
+        ] = None,
     ) -> dict[str, Any]:
         return await handlers.run_deployment(
             deployment_id=deployment_id,