misc: use structured path for errors

docs/durable_run_operations.md

@@ -36,6 +36,10 @@ wf.workflow.run_deployment
 projected as newly-created MCP tools in the current session; many clients do
 not rebuild callable schemas after `tools/list` changes.
 
+These run tools are MCP control tools, not graph-usable workflow capabilities.
+They are discovered through MCP `tools/list` or harness search-tools, not through
+`wf.workflow.list_capabilities`.
+
 ## `run_deployment`
 
 Starts one deployment execution:

docs/wf_mcp_end_to_end_runbook.md

@@ -447,6 +447,11 @@ wf.workflow.validate_deployment
 wf.workflow.run_deployment
 ```
 
+`wf.workflow.list_capabilities` only lists graph-usable workflow capabilities.
+Control tools such as `wf.workflow.inspect_run`, `wf.workflow.read_run_trace`,
+draft workspace mutation helpers, and admin operations are discovered through
+MCP `tools/list` or the client's search-tools surface.
+
 ## Common Failure Points
 
 ### The connection exists but nothing is discoverable

docs/wf_mcp_operator_manual.md

@@ -102,6 +102,15 @@ Typical tools:
 The workflow surface is intentionally split by job. Use the primary path first;
 the advanced tools exist for debugging, compatibility, or focused repair.
 
+There are two discovery paths:
+
+- `wf.workflow.list_capabilities` / `inspect_capability` discover
+  workflow-facing node specs and saved wrappers that can be placed in graphs.
+- MCP `tools/list` or harness search-tools discover control tools such as
+  `wf.workflow.inspect_run`, `wf.workflow.read_run_trace`, draft workspace
+  mutators, and admin operations. These are not workflow capabilities and will
+  not appear in `list_capabilities`.
+
 ### Discovery
 
 Primary:
@@ -279,6 +288,11 @@ nodes rather than source ownership. Its rows include `source_id`, outcomes, and
 top-level input/output field names, while full JSON schemas stay behind
 `wf.workflow.inspect_capability`.
 
+Do not use `list_capabilities` to find MCP control tools. Run/debug helpers such
+as `wf.workflow.inspect_run` and `wf.workflow.read_run_trace` are ordinary MCP
+tools, not graph nodes. Discover them through MCP `tools/list`, search-tools, or
+the tool map in this manual.
+
 `wf.workflow.call_capability` is the REPL-style test step. Its result is
 self-describing: `kind` is either `node_spec` or `wrapper_artifact`,
 `source_id` identifies the owner when applicable, and `diagnostics` is empty for
@@ -317,6 +331,10 @@ wf.workflow.inspect_capability
 
 Use the compact list first, then inspect only the likely candidates.
 
+This list intentionally excludes control-plane MCP tools. If the client needs
+to inspect a run, patch a workspace, or call an admin operation, use MCP
+tool/search discovery instead of workflow capability discovery.
+
 ### 3. Test One Capability Directly
 
 ```text
@@ -446,6 +464,12 @@ A raw tool can be directly callable and still be an awkward workflow node if it
 uses provider-specific result envelopes, status strings, or transport-level
 errors where a graph wants explicit outcomes.
 
+For the common MCP shape `content: [{type: "text", text: "..."}]`, generated
+workflow capabilities keep `output.content` raw. `content` may contain text,
+images, resources, or mixed blocks, so wrapper hints do not invent a top-level
+`output.text`. Add an explicit wrapper/extraction node when a workflow wants a
+specific content-block field.
+
 ### Artifact Versus Deployment
 
 An artifact is the immutable saved workflow definition.

docs/workflow_capabilities.md

@@ -199,6 +199,13 @@ while the graph wants:
 }
 ```
 
+MCP text content blocks are a common provider-envelope case. When an MCP tool
+returns exactly one text content block, the SDK keeps the raw `content` list and
+also exposes a convenience `text` field. Wrapper hints prefer `text` so a string
+state field can map the actual text without writing the raw content-block list.
+Multiple content blocks or non-text content still require explicit wrapper
+decisions.
+
 ### Human-Friendly Versus Graph-Friendly Inputs
 
 A raw tool may be good for interactive human use but awkward for stateful graph

docs/workflow_drafts.md

@@ -607,6 +607,11 @@ It does not guess that a normal output state path is also an error message.
 Provider-specific error envelopes still belong in saved wrapper artifacts or
 follow-up patches.
 
+`error_message_source` accepts the same structural graph path shape used by
+other mapping fields, for example
+`{"root": "state", "parts": ["error_message"]}`. Legacy strings such as
+`state.error_message` remain accepted for compatibility.
+
 In MCP Inspector, workspace mutation tools accept a single `request` object.
 This is deliberate: the request object carries descriptions and validation for
 the authoring envelope while raw JSON Schema fields remain plain JSON objects.