From 8bd9b9e922c4024c7475363e4018fb70d9575cac Mon Sep 17 00:00:00 2001
From: jade <jade.kimhs@gmail.com>
Date: Mon, 17 Aug 2026 15:11:46 +0900
Subject: [PATCH] feat(manifest): expose tool usage guidance

---
 .../dap/lib/manifest/ToolManifestMeta.java           |  6 +++++-
 .../dap/lib/manifest/ToolManifestService.java        |  3 ++-
 .../dap/mcc/manifest/ToolManifestServiceTest.java    | 12 +++++++++++-
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestMeta.java b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestMeta.java
index f21ba07e..817b8d89 100644
--- a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestMeta.java
+++ b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestMeta.java
@@ -1,5 +1,6 @@
 package io.shinhanlife.dap.lib.manifest;
 
+import com.fasterxml.jackson.annotation.JsonProperty;
 import java.util.List;
 
 /** Operational metadata exposed by the Tool Service manifest. */
@@ -11,5 +12,8 @@ public record ToolManifestMeta(
         List<String> tags,
         String legacyInterfaceId,
         List<String> requiredEnvKeys,
-        String ownerOrg) {
+        String ownerOrg,
+        @JsonProperty("when_to_use") String whenToUse,
+        @JsonProperty("when_not_to_use") String whenNotToUse,
+        @JsonProperty("io_limits") String ioLimits) {
 }
diff --git a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestService.java b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestService.java
index c76a4726..5215ee99 100644
--- a/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestService.java
+++ b/dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestService.java
@@ -68,7 +68,8 @@ public class ToolManifestService {
                         tool.getTimeoutMillis() == null ? DEFAULT_TIMEOUT_MILLIS : tool.getTimeoutMillis(),
                         tool.getEnabled() == null || tool.getEnabled(),
                         defaultList(tool.getExampleQueries()), defaultList(tool.getTags()),
-                        tool.getMciServiceId(), defaultList(tool.getRequiredEnvKeys()), tool.getOwnerOrg()));
+                        tool.getMciServiceId(), defaultList(tool.getRequiredEnvKeys()), tool.getOwnerOrg(),
+                        tool.getWhenToUse(), tool.getWhenNotToUse(), tool.getIoLimits()));
     }
 
     private void validate(List<ToolManifestItem> tools) {
diff --git a/dap-was-lib/src/test/java/io/shinhanlife/dap/mcc/manifest/ToolManifestServiceTest.java b/dap-was-lib/src/test/java/io/shinhanlife/dap/mcc/manifest/ToolManifestServiceTest.java
index 85de539b..cd3be693 100644
--- a/dap-was-lib/src/test/java/io/shinhanlife/dap/mcc/manifest/ToolManifestServiceTest.java
+++ b/dap-was-lib/src/test/java/io/shinhanlife/dap/mcc/manifest/ToolManifestServiceTest.java
@@ -16,7 +16,7 @@ class ToolManifestServiceTest {
     private final ObjectMapper objectMapper = new ObjectMapper();
 
     @Test
-    void buildsStandardManifestAndDerivesRevisionFromToolDefinition() {
+    void buildsStandardManifestAndDerivesRevisionFromToolDefinition() throws Exception {
         McpProperties properties = manifestProperties("insurance-processing", "processing.");
         ToolManifestService service = new ToolManifestService(
                 () -> List.of(tool("processing.contract.inquiry", "1.2.0", 3000)), objectMapper, properties);
@@ -35,6 +35,13 @@ class ToolManifestServiceTest {
         assertTrue(item.annotations().readOnlyHint());
         assertEquals("1.2.0", item.meta().version());
         assertEquals(3000, item.meta().timeoutMillis());
+        assertEquals("when to use", item.meta().whenToUse());
+        assertEquals("when not to use", item.meta().whenNotToUse());
+        assertEquals("io limits", item.meta().ioLimits());
+        String payload = objectMapper.writeValueAsString(manifest);
+        assertTrue(payload.contains("\"when_to_use\":\"when to use\""));
+        assertTrue(payload.contains("\"when_not_to_use\":\"when not to use\""));
+        assertTrue(payload.contains("\"io_limits\":\"io limits\""));
         assertEquals(List.of("계약 상태를 알려줘", "내 계약을 조회해줘", "계약번호로 찾아줘"),
                 item.meta().exampleQueries());
     }
@@ -91,6 +98,9 @@ class ToolManifestServiceTest {
                 .exampleQueries(List.of("계약 상태를 알려줘", "내 계약을 조회해줘", "계약번호로 찾아줘"))
                 .tags(List.of("계약"))
                 .ownerOrg("MCP_TOOL")
+                .whenToUse("when to use")
+                .whenNotToUse("when not to use")
+                .ioLimits("io limits")
                 .parametersSchema(Map.of("type", "object", "properties", Map.of("contractNo", Map.of("type", "string")),
                         "required", List.of("contractNo"), "additionalProperties", false))
                 .semver(version)