From 61bbbe50d45589a4786073b44d3a343aba4a09ef Mon Sep 17 00:00:00 2001
From: Lucio Lelii <lucio.lelii@isti.cnr.it>
Date: Thu, 3 Sep 2026 07:52:52 +0200
Subject: [PATCH] Sharpen block descriptions and add placeholder tips

Rewrites the MCPAgent and MCPAgentChat descriptions so the catalog says what the
blocks are actually for - calling a declared MCP server's tools - and when to
prefer them over HTTPServerCall or LLMBlock.

Adds a tip and acceptVariableAsPlaceholder to the two human-facing block
configurations, spelling out how ${{}} placeholders behave: in the interactive
block each one becomes a real named input, while in the decision block they are
additional read-only context alongside the forwarded input port.
---
 .../configurations/HumanDecisionBlockConfiguration.java      | 5 ++++-
 .../configurations/HumanInteractiveBlockConfiguration.java   | 4 +++-
 .../workflow/manager/blocks/types/MCPAgentBlockType.java     | 2 +-
 .../workflow/manager/blocks/types/MCPAgentChatBlockType.java | 2 +-
 4 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanDecisionBlockConfiguration.java b/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanDecisionBlockConfiguration.java
index e5b7f0b..e9b7f5a 100644
--- a/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanDecisionBlockConfiguration.java
+++ b/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanDecisionBlockConfiguration.java
@@ -27,7 +27,10 @@ import lombok.NonNull;
 public class HumanDecisionBlockConfiguration extends BlockConfiguration<HumanDecisionBlockType> {
 
     @UiOrder(30)
-    @LongText(placeholder = "Ask the decision question")
+    @LongText(
+            placeholder = "Ask the decision question",
+            tip = "Use ${{}} placeholders to pull in extra context the person deciding should see, for example: Given ${{cv}}, should this candidate move forward? The block always keeps a separate 'input' port that is forwarded unchanged to whichever option is chosen - placeholders here are additional read-only context, not that forwarded payload.",
+            acceptVariableAsPlaceholder = true)
     @NotBlank
     @Size(max = 2000)
     @JsonProperty(required = true)
diff --git a/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanInteractiveBlockConfiguration.java b/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanInteractiveBlockConfiguration.java
index 98288e0..059b49d 100644
--- a/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanInteractiveBlockConfiguration.java
+++ b/src/main/java/it/cnr/isti/workflow/manager/blocks/configurations/HumanInteractiveBlockConfiguration.java
@@ -21,7 +21,9 @@ public class HumanInteractiveBlockConfiguration extends BlockConfiguration<Human
 
     @NotBlank
     @LongText(
-            placeholder = "Describe the human task")
+            placeholder = "Describe the human task",
+            tip = "Use ${{}} placeholders to reference data produced by an earlier block, for example: Review the following CV: ${{cv}}. Each placeholder becomes a real named input wired by the CONNECTIONS step; without any placeholder the block falls back to a single generic 'input' port.",
+            acceptVariableAsPlaceholder = true)
     @JsonProperty(required = true)
     private String actionDescription;
 
diff --git a/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentBlockType.java b/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentBlockType.java
index 23df418..f2c2bcd 100644
--- a/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentBlockType.java
+++ b/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentBlockType.java
@@ -17,7 +17,7 @@ public class MCPAgentBlockType implements BlockType {
 
     @Override
     public String getDescription() {
-        return "A non-interactive MCP agent call that can use MCP tools and can open, share, or reuse a persistent MCP session. Use it when workflow steps need shared memory/state across nodes, such as indexing then querying, RAG/retrieval, remembered context, or tool-backed knowledge. Set shareSession/sharedSessionName on the producer and useSharedSession/sharedSessionRef on later consumers.";
+        return "A non-interactive step that calls tools exposed by a declared MCP server - this is the primary way to write files to a workspace, build/compile code, run shell commands, query a database, download URLs, or run indexing/retrieval/RAG, and it should be preferred over HTTPServerCall or LLMBlock whenever a declared MCP server's tools already cover the task. It can also open, share, or reuse a persistent MCP session when workflow steps need shared memory/state across nodes (indexing then querying, RAG/retrieval, remembered context): set shareSession/sharedSessionName on the producer and useSharedSession/sharedSessionRef on later consumers.";
     }
 
     @Override
diff --git a/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentChatBlockType.java b/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentChatBlockType.java
index c930bb7..8c8d0eb 100644
--- a/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentChatBlockType.java
+++ b/src/main/java/it/cnr/isti/workflow/manager/blocks/types/MCPAgentChatBlockType.java
@@ -17,7 +17,7 @@ public class MCPAgentChatBlockType implements BlockType {
 
     @Override
     public String getDescription() {
-        return "A human-interactive MCP agent chat block with a persistent MCP session. Use it for conversational workflows that need a user-facing chat plus shared MCP memory/state; for non-interactive shared-memory steps use MCPAgent.";
+        return "A human-interactive chat block whose LLM can call tools exposed by a declared MCP server (writing files, running shell commands, querying a database, downloading URLs, indexing/retrieval/RAG, ...) while talking to a user, and can keep a persistent MCP session across turns/nodes. Use it whenever a chat-facing step needs those MCP tools or shared memory/state; for the same tool-running/shared-memory need without a user in the loop, use MCPAgent instead.";
     }
 
     @Override