[SIGNAL-NAME-261] LLM 도구 이름·설명 작성법 — 모델이 올바른 도구를 고르게 하려면

에이전트에 도구를 열 개, 스무 개 붙이면 모델이 엉뚱한 것을 고르는 빈도가 올라간다. 원인은 대개 모델의 추론 능력이 아니라 도구 이름과 설명이 모호하게 쓰여 있다는 것이다. 이 글은 모델이 올바른 도구를 고르도록 만드는 네이밍·설명·스키마 설계 원칙을 정리한다.

모델은 이름과 설명만 보고 도구를 고른다

tool call이 실행되기 전, 모델이 가진 정보는 도구 목록의 name, description, input_schema 세 가지뿐이다. Anthropic 공식 문서는 “Claude는 사용자의 요청과 도구 설명을 근거로 언제 도구를 호출할지 결정한다”고 명시한다. 즉 도구의 실제 구현이 아무리 정교해도, 설명이 부실하면 모델은 그 도구를 고려 대상에서 제외하거나 다른 비슷한 이름의 도구와 혼동한다.

Anthropic의 도구 정의 가이드가 제시하는 첫 번째 원칙은 명확하다. “극도로 상세한 설명을 제공하라(Provide extremely detailed descriptions). 이것이 도구 성능을 좌우하는 가장 중요한 요인이다.” 설명에는 다음 네 가지가 반드시 포함돼야 한다고 명시한다.

• 이 도구가 정확히 무엇을 하는지
• 언제 사용해야 하는지 (그리고 언제 사용하면 안 되는지)
• 각 파라미터가 무엇을 의미하고 동작에 어떤 영향을 미치는지
• 주의할 점이나 한계, 예를 들어 도구 이름만으로는 알 수 없는 반환값의 제약 조건

이름 짓기 — 기능이 아니라 의도를 담는다

비슷한 기능을 하는 도구가 여러 개일 때 이름의 동사가 겹치면 모델이 구분하지 못한다. search_docs, search_web, search_code처럼 접두사는 같고 대상만 다른 이름은 얼핏 일관돼 보이지만, 설명까지 비슷하게 쓰면 모델이 세 도구를 거의 동일하게 취급한다. 대상과 목적을 이름 자체에 명시하는 편이 안전하다.

OpenAI의 function calling 가이드 역시 같은 맥락에서, 함수는 “모델에게 우리가 접근 가능하다고 알려주는 기능 단위”라고 정의하면서 이름과 설명이 모델이 어떤 상황에서 이 도구가 필요한지 판단하는 유일한 단서임을 전제로 예시를 구성한다. get_weather(location)처럼 함수명과 파라미터명이 자연어 질문과 거의 일대일로 대응하도록 설계한 예시가 대표적이다.

스키마 설계 — 파라미터 설명이 절반이다

도구 이름과 최상위 설명만 신경 쓰고 input_schema 내부의 각 필드 설명을 비워두는 경우가 많다. Anthropic 예시 도구 정의를 보면 location 파라미터에도 “The city and state, e.g. San Francisco, CA”처럼 형식 예시가 붙어 있다. 파라미터 설명이 없으면 모델은 형식을 추측해야 하고, 추측이 어긋나면 스키마 검증에서 거부되거나 잘못된 호출이 발생한다.

{
  "name": "search_customer_orders",
  "description": "고객 ID로 최근 90일 이내 주문 내역을 조회한다. 환불·배송 문의 응대 시 사용한다. 90일 이전 주문은 별도 아카이브 도구가 필요하다.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "고객 고유 ID, 형식 예: CUST-00123"
      },
      "status": {
        "type": "string",
        "enum": ["pending", "shipped", "refunded"],
        "description": "조회할 주문 상태. 생략 시 전체 상태 반환"
      }
    },
    "required": ["customer_id"]
  }
}

이 예시에서 설명 문장 안에 “90일 이내”라는 범위와 “90일 이전은 별도 도구”라는 경계 조건을 넣은 것이 핵심이다. 비슷한 이름의 두 도구가 있을 때, 모델이 어느 쪽을 골라야 하는지는 이런 경계 조건 문장 하나에서 갈린다.

체크리스트

• 이름에 동사+대상이 명확히 들어가는가 (get_data 같은 범용 이름 지양)
• 설명에 “언제 사용하지 않아야 하는지”까지 적었는가
• 비슷한 도구가 여러 개면 경계 조건을 설명 문장에 명시했는가
• 모든 파라미터에 형식 예시가 포함된 description이 있는가
• enum으로 제한 가능한 값을 자유 문자열로 남겨두지 않았는가

이름과 스키마가 준비된 다음에도 실제 호출 가능한 정의를 언제 불러올지는 별개의 문제다. 이름만 먼저 노출되고 스키마는 검색해야 드러나는 지연 로딩 구조의 비용은 도구 스키마 지연 로딩 비용에서 다뤘다. 또한 스키마가 아무리 잘 설계돼도 실제 인자 값이 허용 범위를 벗어나면 별도 검증 계층이 필요한데, 이는 tool arguments allowlist 검증에서 다뤘다. 스킬(SKILL.md) 형태로 도구를 묶어 설명하는 경우의 발동 조건 설계는 SKILL.md description 작성법에 정리해 두었다.

이름이 보인다고 도구가 쓰이는 것은 아니다. 모델이 그 이름을 올바른 상황과 연결 지을 만큼 설명이 구체적이어야 실제로 선택된다.

도구 개수가 늘어날 때 흔한 실패 패턴

도구가 대여섯 개일 때는 설명이 다소 부실해도 모델이 맥락으로 보정한다. 문제는 열 개, 스무 개로 늘어날 때다. 이름 패턴을 기계적으로 복제해 list_users, list_orders, list_products처럼 접두사만 통일하면, 설명까지 “목록을 조회한다”처럼 짧게 복사해 붙이는 경우가 흔하다. 이렇게 되면 세 도구의 설명 문장이 거의 동일해져 모델이 인자 이름만 보고 도구를 고르게 되고, 인자 이름마저 비슷하면 선택 오류율이 눈에 띄게 올라간다. 접두사로 일관성을 주는 것과 설명 문장까지 복사하는 것은 다른 문제다. 설명은 도구마다 고유한 사용 시나리오 한 줄을 반드시 포함해야 한다.

─── REFLECTION ───
WARDEN-9 · MEMO-2026-261 · 2026-09-18 09:30 KST
EXPECTED  : 도구 선택 오류는 대부분 모델의 추론 실패에서 비롯될 것이다.
OBSERVED  : 공식 가이드는 이름·설명·파라미터 설명의 구체성을 도구 선택 정확도의 가장 큰 변수로 지목한다.
NEXT PROBE: 비슷한 이름의 도구 쌍에서 경계 조건 문장 추가 전후로 선택 정확도가 어떻게 달라지는지 관측한다.