feat: publish tool manifest endpoint

README.md

@@ -466,4 +466,107 @@ MCP SDK 표준 tools/list, tools/call
 
 ---
 
-문서에 없는 업무·보안·배포 기준은 임의로 추가하지 말고 AA 및 플랫폼 운영 기준과 먼저 합의합니다.
+문서에 없는 업무·보안·배포 기준은 임의로 추가하지 말고 AA 및 플랫폼 운영 기준과 먼저 합의합니다.
+## Input/Output Schema 작성 가이드
+
+Tool Schema는 Agent가 Tool을 정확히 호출하고, 반환값의 의미를 일관되게 해석하도록 하는 계약입니다. 인증 정보·사번·주민번호 등 민감정보(PII)는 Input/Output Schema와 Tool 응답에 포함하지 않습니다.
+
+### Input Schema
+
+Input Schema는 Agent가 Tool에 전달하는 파라미터의 이름, 타입, 필수 여부, 허용값, 형식 등을 정의합니다.
+
+적용 우선순위는 다음과 같습니다.
+
+1. `inputSchemaResource` — 복잡한 규칙을 담은 JSON Schema 리소스
+2. `inputSchema` — 어노테이션에 직접 선언한 JSON Schema
+3. 요청 DTO 필드의 `@McpValidation` — 자동 JSON Schema 생성
+
+단순한 요청 DTO는 `@McpValidation`만으로 관리합니다.
+
+```java
+public class ClaimSearchRequest {
+
+    @McpValidation(required = true, pattern = "^CLM[0-9]{13}$")
+    private String claimNo;
+
+    @McpValidation(minimum = 1, maximum = 100)
+    private Integer size;
+}
+```
+
+### Output Schema
+
+Output Schema는 Tool이 반환하는 결과의 타입과 의미를 정의합니다. `BusinessToolController`는 Tool 실행 후 반환값을 Output Schema 기준으로 검증합니다.
+
+적용 우선순위는 다음과 같습니다.
+
+1. `outputSchemaResource` — 조건부 필드·중첩 배열 등 복잡한 규칙을 담은 JSON Schema 리소스
+2. `outputSchema` — 어노테이션에 직접 선언한 JSON Schema
+3. 반환 DTO의 `@McpOutputSchema`와 필드 `@McpValidation` — 자동 JSON Schema 생성
+4. 위 설정이 모두 없으면 Output Schema 검증을 수행하지 않음
+
+따라서 단순한 응답은 별도 `outputSchemaResource` 없이 반환 DTO에 `@McpOutputSchema`를 선언하면 됩니다. `null`이 정상 값일 수 있는 필드는 `nullable = true`를 반드시 지정합니다.
+
+```java
+@McpOutputSchema
+public class ClaimSearchResponse {
+
+    @McpValidation(required = true, allowedValues = {"SUCCESS", "FAILURE"})
+    private String resultCode;
+
+    @McpValidation(nullable = true, minimum = 0)
+    private Long approvedAmount;
+}
+```
+
+### 복잡한 Schema는 Tool 모듈별 리소스로 관리
+
+조건부 응답, 중첩 DTO, 배열 정렬 기준처럼 어노테이션만으로 표현하기 어려운 규칙은 Tool Core가 아니라 각 Tool 모듈의 리소스에 JSON Schema로 둡니다.
+
+```text
+src/main/resources/
+└─ tool-schemas/
+   └─ {categoryKey}/
+      ├─ claim-search-resource-input-schema.json
+      └─ claim-search-resource-output-schema.json
+```
+
+예를 들어 `categoryKey`가 `cmm`이면 아래와 같이 선언합니다.
+
+```java
+@McpFunction(
+    name = "sample.claim.search.resource",
+    inputSchemaResource = "classpath:tool-schemas/cmm/claim-search-resource-input-schema.json",
+    outputSchemaResource = "classpath:tool-schemas/cmm/claim-search-resource-output-schema.json"
+)
+public ClaimSearchResponse search(ClaimSearchRequest request) {
+    // ...
+}
+```
+
+`inputSchemaResource`와 `outputSchemaResource`는 복잡한 경우에만 선언합니다. 단순한 Tool까지 JSON 파일을 별도 생성할 필요는 없습니다.
+
+### Output 설계 규칙
+
+- 코드와 표시용 라벨을 함께 반환합니다. 예: `status` + `statusLabel`
+- `null`이 정상인 값은 의미를 설명에 명시하고 DTO에는 `nullable = true`를 설정합니다.
+- 조건부 필드는 어떤 조건에서 값이 존재하는지 JSON Schema에 명시합니다.
+- 배열은 정렬 기준을 설명에 명시합니다. 예: `접수일 내림차순`
+- 목록 응답에는 추가 조회 여부를 나타내는 `hasMore`를 포함합니다.
+- 민감정보는 마스킹보다 **응답에서 제외**하는 것을 우선합니다.
+
+### 실행 로그 및 확인
+
+Tool 실행이 끝나면 아래 로그는 Schema 정의가 아니라 **검증을 통과한 실제 최종 응답값**을 출력합니다.
+
+```text
+[Tool -> MCP Gateway] Output Schema Result: { ... }
+```
+
+따라서 로그에도 실제 응답이 남으므로, 응답 DTO와 Output Schema에 민감정보가 포함되지 않도록 설계해야 합니다.
+
+스키마 리소스와 DTO 기반 자동 Schema는 아래 테스트로 함께 검증할 수 있습니다.
+
+```powershell
+.\gradlew.bat :dap-tool-oth:test --tests "io.shinhanlife.dap.mcc.biz.cmm.dto.ClaimSearchRequestSchemaTest"
+```