CCAF 101

Tool Interface Design

8 min read

Tool Interface Design

이 문서는 CCAF Domain 2를 이해하기 위한 개념 설명용 노트다.
여기서는 개별 도구 하나가 모델에게 어떻게 보이는지를 다룬다. 즉 tool interface를 단순한 함수 시그니처가 아니라, 모델이 도구를 이해하는 표면(surface) 으로 이해하는 데 초점을 둔다.

Tool interface란 무엇인가

Agent Loop에서 에이전트에게 도구는 내부 구현보다 먼저 이름, 설명, 입력 스키마로 보인다.
즉 모델은 보통 도구의 소스코드를 읽고 판단하는 것이 아니라, 런타임이 노출한 인터페이스를 보고:

  • 이 도구가 무엇을 하는지
  • 어떤 입력이 필요한지
  • 어떤 결과를 기대해야 하는지
  • 어떤 상황에서 적절한지

를 추론한다.

즉 tool interface는 단순한 개발자 문서가 아니라,

모델이 도구를 이해하는 방식 자체를 형성하는 실행 인터페이스

다.

왜 interface design이 중요한가

도구 구현이 아무리 좋아도, 인터페이스가 모호하면 모델은 도구를 안정적으로 이해할 수 없다.

예를 들어:

  • 이름이 지나치게 추상적이거나
  • 설명이 짧고 뭉뚱그려져 있거나
  • 입력 필드 이름이 애매하거나
  • 필수 조건이 설명에 빠져 있으면

모델은:

  • 도구의 용도를 넓거나 잘못되게 해석하거나
  • 입력을 부정확하게 채우거나
  • 가능한 호출과 적절한 호출을 구분하지 못할 수 있다

즉 도구 실패는 구현 버그 때문만이 아니라,

모델이 읽는 인터페이스 자체가 애매해서 생기는 이해 실패

일 수도 있다.

모델은 무엇을 보고 도구를 이해하는가

개별 도구 관점에서 핵심은 세 가지다.

1. 이름

도구 이름은 가장 압축된 의미 신호다.
이름만 보고도 대략적인 기능과 대상이 드러나야 한다.

예:

  • get_customer_profile
  • lookup_order_status
  • process_refund

반대로:

  • handle_data
  • run_task
  • do_action

같은 이름은 지나치게 추상적이라 도구 이해를 흐린다.

2. 설명(description)

설명은 “무엇을 하는가”를 넘어서, 어떤 입력을 기대하며 어떤 맥락에서 쓰이는가를 알려줘야 한다.

즉 좋은 설명은:

  • 기능
  • 입력 기대값
  • 사용 맥락
  • 제한 조건

을 함께 드러낸다.

3. 입력 스키마(schema)

입력 필드의 이름과 구조는 모델이 실제 호출을 조립하는 데 직접 영향을 준다. Schema Design for Reliability에서 더 깊이 다룬다.

즉 schema는 단순 validation 장치가 아니라,

모델의 호출 조립 행동을 유도하는 구조

다.

좋은 도구 설명은 어떤 설명인가

좋은 설명은 짧기만 한 설명이 아니다.
핵심은 도구의 사용 맥락이 드러나는 설명이다.

예를 들어 좋지 않은 설명:

“고객 정보를 조회합니다.”

이 설명은 기능은 말하지만,

  • 어떤 고객 식별자를 기대하는지
  • 어떤 상황에서 쓰는지
  • 무엇을 돌려주는지

가 불분명하다.

더 좋은 설명은 예를 들면:

“검증된 customer ID를 사용해 고객 프로필과 계정 상태를 조회합니다. 환불, 계정 검증, 주문 이슈 조사 전에 사용합니다.”

이 설명은:

  • 무엇을 하는지
  • 어떤 입력을 기대하는지
  • 어떤 업무 맥락에서 쓰는지

를 함께 알려준다.

즉 좋은 description은 기능 요약이 아니라,

도구를 올바르게 이해하게 만드는 사용 가이드

에 가깝다.

입력 스키마는 왜 중요한가

모델은 입력 필드를 채울 때 필드 이름과 구조에 강하게 의존한다.

예를 들어:

  • id
  • customer
  • customerId
  • verifiedCustomerId

는 비슷해 보여도 의미가 다르다.

특히 위험한 경우는:

  • 너무 짧거나
  • 지나치게 일반적이거나
  • 서로 다른 개념을 한 필드에 섞어 두는 것

이다.

좋은 필드 설계의 특징은:

  • 의미가 분명하고
  • 서로 다른 개념이 분리되어 있고
  • required field가 선명하고
  • 형식 기대값이 드러난다는 점이다.

즉 schema 품질은 validation만이 아니라, 모델의 오해 가능성을 줄이는 설계다.

추상적 설명보다 구체적 affordance가 낫다

도구 설명은 “이 도구는 강력합니다” 같은 추상적 문장보다,
이 도구가 어떤 상황에서 무엇을 해주는지를 구체적으로 드러내는 편이 좋다.

예:

  • “환불 전에 고객 상태를 확인할 때 사용”
  • “외부 공개 웹 검색 전용”
  • “내부 문서 저장소에서 문서 제목과 본문을 검색”
  • “파일 내용을 수정하지 않고 읽기만 함”

이런 affordance가 선명할수록, 모델은 도구의 성격을 더 안정적으로 이해한다.

즉 좋은 interface design은 멋진 문장을 쓰는 것이 아니라,

모델이 오해하기 어려운 이해 표면을 만드는 일

이다.

흔한 오해

“설명은 짧을수록 좋다”

아니다. 너무 짧으면 사용 맥락과 입력 기대값이 사라진다.

“이름만 명확하면 설명은 대충 써도 된다”

그렇지 않다. 실제 이해 품질은 이름 + 설명 + schema가 함께 결정한다.

“스키마는 validation만 통과하면 된다”

아니다. 스키마는 모델이 호출을 조립하는 인터페이스이기도 하다.

한 문장 요약

Tool interface design은 도구 구현을 설명하는 작업이 아니라, 모델이 개별 도구를 올바르게 이해하도록 만드는 설계 작업이다.

관련 개념

그래프 뷰

백링크