도구 호출은 모델의 문장을 실행 권한으로 바꾸는 경계입니다. 따라서 이름을 잘 짓는 것만으로는 부족하고, 입력의 형식·업무 의미·현재 상태·인가·실제 결과를 순서대로 확인해야 합니다. 이 노트에서는 특히 조회와 변경, 확정된 성공과 실행 여부를 알 수 없는 상태를 분리해 판단합니다.
환불 견적과 환불 실행 도구의 의도 구분
update_item에 조회·환불·삭제를 모두 숨기면 모델이 이름만 보고 효과를 추측해야 합니다. get_order, prepare_refund, execute_refund처럼 의미를 나눌 수 있습니다. 반대로 내부 함수마다 노출하면 선택지가 폭증하므로 사용자 과제 단위로 묶고 “견적은 돈을 돌려주지 않는다” 같은 반례를 설명합니다.
입력 계약에는 ID를 발급한 시스템, 통화, 금액의 최소 단위, 시간대, 필드를 생략한 경우와 null을 넣은 경우의 차이를 적습니다. 예를 들어 amount:1000만 받으면 1000원인지 10달러인지 판단할 수 없습니다. tenant 범위와 사용자 권한은 모델이 인자로 고르는 값이 아니라 인증된 실행 문맥에서 가져옵니다.
유효 JSON과 주문 소유권 검증
| 검사 | 확인하는 것 | 다음 단계가 필요한 이유 |
|---|---|---|
| 완성·파싱 | 응답 종료·유효한 JSON | 거절·잘림·stream 단절 가능 |
| schema | 타입·enum·허용 조합 | ID가 실재하는지 모름 |
| domain | 통화·환불 가능액·현재 version | 다른 사용자일 수 있음 |
| authorization | 사용자·대상·행동 | 별도 사람 승인 필요 가능 |
| effect verification | 실제 원장·결과 ID | 접수만 됐을 수 있음 |
status:not_found인데 예약 ID가 존재하는 모순도 검사합니다. schema가 표현할 수 있는 관계는 표현하되 API의 지원 부분집합을 확인하고 나머지는 코드로 검증합니다. 거절·needs_input·unsupported를 표현할 수 있게 해야 정보가 없을 때 임의 값으로 형식을 채우지 않습니다.
그림을 글로 읽기
- 완성된 모델 출력
- 형식·필드 관계 검사
- 현재 대상·업무 조건·인가
- 필요한 승인·버전 대조
- 실행과 실제 결과 확인
- 완성된 모델 출력 → 형식·필드 관계 검사: 미완료 제외
- 형식·필드 관계 검사 → 현재 대상·업무 조건·인가: 타입 이후 의미
- 현재 대상·업무 조건·인가 → 필요한 승인·버전 대조: 허용 범위
- 필요한 승인·버전 대조 → 실행과 실제 결과 확인: 검증된 요청
출력 구체성과 복구 행동 선택 기준
사전 인자 오류를 반환할 때는 어느 필드가 잘못됐고 어떤 값의 범위가 허용되는지 함께 적으며, 권한 부족은 재인가가 필요한지 아니면 거절인지 구분해 반환합니다. timeout이 나면 실행되지 않았다고 단정하지 말고, 논리 작업 ID와 나중에 확인할 조회 경로를 반환합니다. 10개 변경 중 7개가 성공한 경우에는 성공한 7개의 ID와 미완료 3개를 나눠 기록하고, 전체를 다시 호출하지 않아 성공한 변경을 중복 실행하지 않도록 합니다. 미완료분을 재시도한다면 그 항목만 대상으로 합니다.
목록이 잘렸다면 truncated, nextCursor, 반환 범위를 표시합니다. 단순히 결과 100개를 반환하고 전체라고 암시하지 않습니다. 출력에는 필요한 원문 참조·버전·단위를 유지하되 token·전체 내부 SQL·비밀 오류를 복제하지 않습니다.
실패를 진단할 때는 먼저 “호출 자체를 허용하지 않았는가”, “호출은 접수됐지만 실행 결과가 확정되지 않았는가”, “실행 결과가 업무적으로 거절됐는가”를 나눕니다. 예를 들어 schema 오류는 모델이 인자를 고쳐 다시 만들 수 있지만, timeout은 같은 변경을 무작정 반복하기보다 작업 ID를 조회해야 합니다. 이 세 분류를 관측 필드와 사용자 응답에도 그대로 반영하면 복구 행동이 달라져야 하는 이유가 드러납니다.
자동 보정과 의미 보존 경계
잘못된 enum은 허용값을 알려 줄 수 있지만 모호한 수신자·금액을 모델이 임의로 채우게 하지 않습니다. 부족한 정보는 사용자에게 확인하고 보정 횟수를 제한합니다. 형식 보정을 위한 모델 재호출이 이미 실행된 변경의 반복 호출과 섞이지 않게 합니다. 모델 confidence는 검증된 확률도 승인 토큰도 아닙니다.
실제 환불 실행이 견적 ID와 version을 요구하게 하면 실행기가 고정된 변경안을 다시 읽을 수 있습니다. 그래도 잔액·소유권·견적 만료는 실행 시점에 검사해야 합니다. read-only·idempotent 주석은 구현의 주장이지 효과를 강제하는 보안 장치가 아닙니다.
도구 선택과 복구 경로 평가
비슷한 조회/삭제 도구, 같은 타입의 잘못된 ID, 단위 혼합, 잘린 stream, 부분 성공, 권한 거절, 오래된 schema를 넣습니다. 도구 선택률·인자 보정 수·잘못된 실행 거절·미확정 보고·출력 bytes를 따로 봅니다. 이 노트는 계약 설계이며 특정 모델의 구조화 출력 신뢰도를 실험한 결과는 아닙니다.