Claude가 선택하는 도구 만들기

이 영상의 데모는 2026년 9월에 녹화되었습니다. 데모는 Claude Sonnet 5(claude-sonnet-5)에서 실행되었습니다. 최신 모델에서는 결과가 다를 수 있습니다.

도구 루프가 작동하다가 다음 중 하나가 발생한다고 가정해 봅시다:

• Claude가 잘못된 도구를 호출합니다.
• 하나의 사실을 위해 세 번의 도구 호출을 합니다.
• 코드가 MEG-2026-0142를 원하는 곳에 0142를 전달합니다.

Claude는 도구를 실행하는 함수를 전혀 받지 않습니다. Claude는 여러분이 보낸 정의와 반환한 결과만 볼 뿐입니다. 그러므로 Claude가 도구를 잘못 사용할 때는 먼저 정의를 살펴보세요.

Meridian은 직원들이 프로젝트, 허가, 청구에 대해 질문할 수 있는 내부 어시스턴트를 가지고 있습니다. 도구 정의를 다시 작성한 결과, 동일한 모델에서 30개 테스트 질문 중 점수가 14점에서 26점으로 올랐습니다.

Claude가 보는 도구의 모습

도구 정의는 Claude에게 도구가 존재한다는 것을 알려주는 JSON 블록입니다. 이는 각 요청의 tools 목록에 담아 보냅니다.

다음은 Meridian의 프로젝트 도구를 다시 작성한 정의입니다. 이는 네 부분으로 구성됩니다.

{
  "name": "lookup_project_status",
  "description": "Returns current facts about a single Meridian …",
  "input_schema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Full Meridian job number in the format MEG-YYYY-NNNN, e.g. MEG-2026-0142."
      },
      "fields": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["phase", "status", "lead", "hours", "deadline", "site", "client"]
        },
        "description": "Which fields to return. Omit to return everything."
      }
    },
    "required": ["project_id"]
  },
  "input_examples": [
    {"project_id": "MEG-2026-0142", "fields": ["phase", "status"]},
    {"project_id": "MEG-2025-0417", "fields": ["lead", "hours"]},
    {"project_id": "MEG-2024-0233"}
  ]
}

• name은 Claude가 그 도구를 부르는 이름입니다.
• description은 여러분이 작성하고 Claude가 읽는 일반 텍스트입니다. 여기서는 짧게 잘려 있으며, 다음 섹션에서 전체를 보여드립니다.
• input_schema는 도구의 매개변수를 JSON Schema로 나열하며, 각 매개변수는 이름, 유형, 그리고 자체 설명을 가집니다. required는 반드시 제공해야 하는 매개변수를 나타냅니다.
• input_examples는 선택 사항입니다. 이는 전체 작업 번호와 같이 좋은 입력이 어떤 모습인지 Claude에게 보여줍니다. 각 예시는 input_schema에 대해 유효해야 하며, 그렇지 않으면 API는 400 오류를 반환합니다.

Claude는 사용자의 요청과 각 도구의 설명을 읽어 도구 호출 여부를 결정합니다.

상세한 설명 작성하기

네 부분 중에서 설명이 가장 큰 역할을 합니다.

최소 서너 문장을 목표로 하고, 도구가 복잡하다면 더 길게 작성하세요. 다음 네 가지를 다루어야 합니다:

1. 도구가 하는 일
2. 언제 사용하고, 언제 사용하지 않는지
3. 각 매개변수가 의미하는 바
4. 반환하지 않는 것

다음은 Meridian의 전체 설명입니다:

Returns current facts about a single Meridian project: phase,
schedule status, project lead, hours budgeted and consumed,
deadline, site city, and client. Use this only when the user asks
about a specific project by name or job number; if only a partial
number is given (e.g. 'the 0142 job'), normalize it to the full
MEG-YYYY-NNNN format before calling. Pass the fields parameter to
fetch just the fields the question needs instead of the whole
record. This tool does not return permit or invoicing information.
Use get_permit_status or get_billing_summary for those.



도구를 언제 사용하고 언제 사용하지 않을지 명시하면 Claude가 잘못된 도구를 호출하지 않도록 도울 수 있습니다. Meridian의 설명은 이 도구를 하나의 프로젝트에 관한 질문으로 한정합니다. 허가와 청구에 대해서는 사용할 도구를 명시합니다.

겹치는 도구를 하나로 합치기

여러 도구가 거의 같은 일을 할 때는 좋은 설명만으로는 큰 도움이 되지 않습니다.

Meridian의 첫 번째 도구 세트는 각각 한 줄 설명만 있는 얇은 도구 여섯 개로 구성되어 있었습니다. 그중 네 개는 각각 하나의 프로젝트 사실을 반환했습니다. 이 네 개는 서로 겹쳤기 때문에, Claude는 어떤 질문에 어떤 도구가 필요한지 추측해야 했습니다.

해결책은 이 네 개를 fields 매개변수를 가진 하나의 도구 lookup_project_status로 합치는 것입니다. 이 매개변수는 반환할 사실을 지정합니다. 허가와 청구를 위한 나머지 두 개는 다른 일을 하므로 그대로 유지합니다. 여섯 개의 도구가 세 개가 됩니다.

평가(eval)로 변화를 측정하기

평가(eval)란 정답이 알려진 고정된 테스트 질문 세트를 Claude에 대해 실행하고 점수를 매긴 것입니다. 이는 새로운 정의가 더 나은지를 보여줍니다.

Meridian의 평가는 Claude가 올바른 도구를 호출하는지 확인합니다. 여기에는 직원이 물어볼 법한 30개의 질문이 있으며, 각각 올바른 도구 호출이 표시되어 있습니다. Meridian은 claude-sonnet-5에서 이 30개의 질문을 도구 세트마다 한 번씩, 총 두 번 실행했습니다.

문제가 있는 부분만 고치기

하나의 실패를 고치려면, 정의에서 문제가 있는 부분을 찾아 그 부분만 바꾸고 평가를 다시 실행하세요.

도구 사용 문제 해결하기에서 더 많은 증상과 해결책을 확인할 수 있습니다.

핵심 요약

• 최소 서너 문장으로 설명을 작성하고, 도구를 언제 사용하지 말아야 하는지도 명시하세요.
• 겹치는 도구를 매개변수를 가진 하나의 도구로 합치세요.
• 평가(eval)로 변화를 측정하세요.
• 하나의 실패를 고치려면 문제가 있는 부분만 바꾸세요.