비슷한 이름의 도구가 많아 에이전트가 잘못된 도구와 인자를 선택합니다. 도구 API는 일반 개발자용 API와 무엇을 다르게 설계하나요?

도구 선택의 목적과 실행 결과가 이름·설명·스키마에서 명확히 드러나게 하겠습니다. 모델이 내부 코드를 읽고 암묵적인 사용법을 알아낼 것이라고 기대하지 않습니다. 도구는 하나의 작업 의도를 표현하고, 입력 제약은 설명만이 아니라 실제 검증 코드로 강제하며, 출력은 다음 판단에 필요한 상태를 반환해야 합니다. 설명이 좋아도 인가와 원자성은 서버의 책임입니다.

모호한 기능을 좁은 계약으로 바꿉니다

update_item 하나에 조회·생성·삭제를 모두 넣기보다 get_order와 prepare_refund, execute_refund처럼 역할을 나눌 수 있습니다. 다만 작은 내부 함수마다 도구를 만들면 선택지가 폭증하므로 사용자가 원하는 작업 단위에 맞춥니다. ID가 어느 시스템의 식별자인지, 금액의 통화와 단위, 생략과 null의 의미, 날짜의 시간대를 명시합니다. 유효한 예시와 흔한 경계 사례는 선택 오류를 줄이지만 예시를 보안 검사 대신 쓰지는 않습니다.

예를 들어 환불 도구에는 주문 ID와 금액만 받지 않고 검증된 견적 ID나 대상 버전을 요구할 수 있습니다. 런타임이 현재 사용자와 소유권을 확인하고 허용 잔액을 다시 계산해야 합니다. 모델이 tenant_id를 제안했다는 이유로 그 테넌트 권한을 부여하지 않습니다. 조회 도구의 read-only 표시도 신뢰할 수 있는 구현과 맞는지 확인하며, 설명을 바꾼 원격 서버를 자동으로 신뢰하지 않습니다.

오류를 복구 가능한 정보로 돌려줍니다

잘못된 인자는 필드와 허용 범위를 알려 주고, 권한 부족은 재시도보다 사용자 인가 절차가 필요하다고 표현합니다. timeout은 실행되지 않았다는 뜻이 아니므로 요청 ID와 결과 조회 경로를 제공합니다. 부분 성공이면 어떤 항목이 바뀌었는지 식별자를 돌려줘야 전체를 다시 실행해 중복 변경하는 일을 막을 수 있습니다. 길이 제한으로 출력이 잘렸다면 그 사실과 다음 페이지 위치를 명시합니다.

도구 품질은 모델에게 설명을 읽혀 보는 것만으로 판단하지 않습니다. 비슷한 도구가 함께 있을 때의 선택 정확도, 인자 수정 횟수, 실패 후 회복률, 반환 데이터 크기를 실제 과제로 측정합니다. 이름 변경이나 예시 추가가 특정 모델에는 도움이 되어도 다른 모델에는 다르게 작용할 수 있으므로 버전별 평가를 유지합니다. 넓은 셸 하나가 항상 나쁜 것도, 세분된 도구가 항상 좋은 것도 아닙니다. 자유도가 필요한 범위와 검증 가능한 실행 경계를 맞추는 것이 목적입니다.

실행 사례로 확인합니다

도구 선택 예제에는 정상 입력만 아니라 비슷한 다른 도구를 써야 하는 반례도 넣을 수 있습니다. '견적 조회는 결제하지 않는다', '실행은 승인된 견적 ID를 요구한다'처럼 목적의 차이를 드러내면 모델이 이름만으로 추측하는 일을 줄입니다. 출력의 금액·시간·대상 ID는 가능한 한 구조화하고, 사람이 읽는 설명과 기계가 검사할 필드를 함께 제공할 수 있습니다. 서버 버전이 바뀌어 필드 의미가 달라졌다면 스키마가 그대로여도 호환 변경이 아닐 수 있으므로 계약 테스트를 유지합니다. 잘못된 호출을 모델이 고치도록 하는 피드백과 서버가 절대 허용하지 않을 인가 실패도 서로 다르게 표현하겠습니다.