From 6ad5c3198615741c37986dadc5657eadc0a9f93c Mon Sep 17 00:00:00 2001
From: jade <jade.kimhs@gmail.com>
Date: Mon, 17 Aug 2026 14:54:35 +0900
Subject: [PATCH] feat(mcp): expose tool guidance in metadata

---
 .../dap/lib/mcp/ToolMetadataMcpMapper.java    |  3 +++
 .../lib/mcp/ToolRegistryHeartbeatSender.java  | 21 ++++++++-----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolMetadataMcpMapper.java b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolMetadataMcpMapper.java
index 8624e60eb..96bab93ac 100644
--- a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolMetadataMcpMapper.java
+++ b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolMetadataMcpMapper.java
@@ -32,6 +32,9 @@ public final class ToolMetadataMcpMapper {
         put(meta, "version", metadata.getSemver());
         put(meta, "category_key", metadata.getCategoryKey());
         put(meta, "display_description", metadata.getDisplayDescription());
+        put(meta, "when_to_use", metadata.getWhenToUse());
+        put(meta, "when_not_to_use", metadata.getWhenNotToUse());
+        put(meta, "io_limits", metadata.getIoLimits());
         put(meta, "example_queries", metadata.getExampleQueries());
         put(meta, "tags", metadata.getTags());
         put(meta, "legacy_interface_id", metadata.getMciServiceId());
diff --git a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolRegistryHeartbeatSender.java b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolRegistryHeartbeatSender.java
index 1e79f37a4..c3deb4ac6 100644
--- a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolRegistryHeartbeatSender.java
+++ b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolRegistryHeartbeatSender.java
@@ -12,7 +12,7 @@ package io.shinhanlife.dap.lib.mcp;
  * 수정일      수정자    수정내용
  * ---------- -------- ---------------------------
  * 2026.09.01  0986406    최초생성
- * 
+ *
  * </pre>
  */
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -91,7 +91,7 @@ public class ToolRegistryHeartbeatSender {
     private String applicationName;
 
     private List<ToolMetadata> registeredTools = new ArrayList<>();
-    
+
     @Getter
     private List<ToolMetadata> allScannedTools = new ArrayList<>();
 
@@ -105,11 +105,11 @@ public class ToolRegistryHeartbeatSender {
         Map<String, Object> allBeans = applicationContext.getBeansOfType(Object.class);
         for (Object bean : allBeans.values()) {
             Class<?> targetClass = AopUtils.getTargetClass(bean);
-            
+
             for (Method method : targetClass.getDeclaredMethods()) {
                 McpTool functionAnnotation = AnnotationUtils.findAnnotation(method, McpTool.class);
                 GrowToolHint hintAnnotation = AnnotationUtils.findAnnotation(method, GrowToolHint.class);
-                
+
                 if (functionAnnotation != null) {
                     String baseName = functionAnnotation.name();
                     String rawSubToolName = functionAnnotation.name();
@@ -141,11 +141,11 @@ public class ToolRegistryHeartbeatSender {
                     meta.setPodUrl(podUrl);
                     meta.setModuleName(applicationName);
                     meta.setEndpoint(podUrl.replaceAll("/+$", "") + "/mcp/" + subToolName);
-                    
+
                     meta.setVisible(true);
                     meta.setIsRegistered(isRegister);
                     meta.setRequiresApproval(hintAnnotation != null && hintAnnotation.requiresApproval());
-                    
+
                     // extract standard hints from @McpTool.annotations()
                     McpTool.McpAnnotations ann = functionAnnotation.annotations();
                     if (ann != null) {
@@ -159,10 +159,10 @@ public class ToolRegistryHeartbeatSender {
                         meta.setIdempotentHint(false);
                         meta.setOpenWorldHint(true);
                     }
-                    
+
                     Map<String, String> prompts = new HashMap<>();
                     meta.setActionPrompts(prompts);
-                    
+
                     if (method.getParameterCount() > 0) {
                         try {
                             Class<?> paramType = method.getParameterTypes()[0];
@@ -207,10 +207,7 @@ public class ToolRegistryHeartbeatSender {
         meta.setWhenToUse(definition.description().whenToUse());
         meta.setWhenNotToUse(definition.description().whenNotToUse());
         meta.setIoLimits(definition.description().ioLimits());
-        meta.setDescription(String.join("\n", definition.description().function(),
-                "사용 시점: " + definition.description().whenToUse(),
-                "사용 제외: " + definition.description().whenNotToUse(),
-                "입출력 제한: " + definition.description().ioLimits()));
+        meta.setDescription(definition.description().function());
         meta.setDisplayDescription(definition.displayDescription());
         meta.setExampleQueries(definition.exampleQueries());
         meta.setReadOnlyHint(definition.readOnly());