Claude API에서 도구(tool)를 정의할 때 이름(name)과 설명(description)을 대충 지으면, Claude가 도구를 엉뚱한 순간에 호출하거나 아예 호출하지 않는 문제가 생깁니다. 이 글은 공식 문서에 나온 이름 짓기 규칙과 설명 작성 규칙을 초보자도 그대로 따라 할 수 있도록 정리한 것입니다. 이미 만들어 둔 도구 정의가 있다면 이 글의 체크리스트로 5~10분 안에 점검할 수 있습니다.
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
시작 전 준비물과 용어 빠른 풀이
이 글을 따라오려면 다음이 준비되어 있으면 됩니다. Claude API 키(콘솔에서 발급), Messages API를 호출해 본 경험(또는 공식 예제 복사 실행), 도구 하나 이상을 tools 파라미터에 넣어 요청해 본 경험입니다. 코드를 처음 다뤄도 아래 용어만 알면 이해할 수 있습니다.
- tool use(도구 사용) — Claude가 답을 모르거나 실제 동작(검색, 계산, DB 조회 등)이 필요할 때, 여러분이 만든 함수를 "호출해 달라"고 요청하는 기능입니다.
- name(이름) — 도구를 식별하는 문자열입니다. Claude가 어떤 도구를 부를지 고를 때 이 이름을 근거로 삼습니다.
- description(설명) — 도구가 무엇을 하는지 사람이 읽는 말로 적은 설명입니다. Claude는 이 설명만 보고 "지금 이 도구를 써야 하나?"를 판단합니다.
- input_schema(입력 스키마) — 도구가 받을 값의 형태를 정의한 JSON Schema(데이터 구조를 정해 놓은 규격)입니다. 예: "location이라는 문자열이 필요하다."
- tool_use 블록 — Claude가 "이 도구를, 이런 입력값으로 호출하겠다"고 응답에 담아 보내는 구조화된 데이터입니다.
도구 이름(name)은 어떻게 지어야 하나요?
도구 이름은 영문 대소문자, 숫자, 밑줄(_), 하이픈(-)만 사용해 최대 64자로 지어야 합니다. 공식 문서는 이 규칙을 정규식(regex, 문자 패턴을 정하는 규칙) ^[a-zA-Z0-9_-]{1,64}$로 명시합니다. 공백, 한글, 마침표, 슬래시 등을 넣으면 요청 자체가 거부됩니다.
글자 규칙만 지킨다고 끝이 아닙니다. 도구가 여러 개, 특히 여러 서비스(깃허브, 슬랙, 데이터베이스 등)에 걸쳐 있다면 서비스명을 접두사로 붙이는 네임스페이스 규칙을 쓰라고 공식 문서는 권합니다. 예를 들어 github_list_prs, slack_send_message처럼요. 이렇게 하면 도구가 늘어나도 Claude가 어떤 서비스의 어떤 동작인지 이름만 보고 헷갈리지 않습니다. 특히 도구를 필요할 때만 불러오는 tool search 기능을 쓸 계획이라면 이 규칙이 더 중요해집니다.
| 상황 | 나쁜 예 | 좋은 예 |
|---|---|---|
| 주식 시세 조회 도구 | get price (공백 포함, 규칙 위반) | get_stock_price |
| 여러 서비스를 함께 다룰 때 | list_prs, send_message (출처 불명확) | github_list_prs, slack_send_message |
| 날씨 조회 도구 | 날씨확인 (한글·정규식 위반) | get_weather |
도구 설명(description)은 무엇을 담아야 하나요?
도구 설명에는 무엇을 하는지, 언제 써야 하는지(그리고 언제 쓰면 안 되는지), 각 파라미터가 무엇을 뜻하는지, 중요한 한계나 주의사항이라는 네 가지가 들어가야 합니다. 공식 문서는 이 네 가지를 "설명이 이해되지 않으면 발생하는 도구 성능 저하의 가장 큰 원인"이라고 지적하며, 도구당 최소 3~4문장, 복잡한 도구라면 더 길게 쓰라고 권합니다.
주의할 점: 설명은 짧을수록 좋은 게 아니라 Claude가 판단에 필요한 정보를 다 담아야
공식 문서의 예시로 좋은 설명과 나쁜 설명을 비교해 보면 차이가 뚜렷합니다.
// 좋은 예
{
"name": "get_stock_price",
"description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}
// 나쁜 예
{
"name": "get_stock_price",
"description": "Gets the stock price for a ticker.",
"input_schema": {
"type": "object",
"properties": { "ticker": { "type": "string" } }
}
}나쁜 예는 문장 하나로 끝나 버려서, Claude가 "이 도구가 배당금이나 시가총액도 알려주나?" 같은 질문에 이 도구를 써야 할지 판단할 근거가 없습니다. 파라미터에도 description이 빠져 있어 ticker에 무엇을 넣어야 하는지(종목 코드인지 회사명인지)조차 불명확합니다.
비슷한 동작은 어떻게 묶어야 하나요?
같은 대상을 다루는 동작들은 도구를 여러 개로 쪼개지 말고 하나의 도구 + action 파라미터로 묶어야 합니다. 공식 문서는 풀 리퀘스트(PR)를 예로 들며, create_pr·review_pr·merge_pr처럼 도구를 따로따로 만들기보다 action 값으로 동작을 구분하는 도구 하나로 합치라고 권합니다. 도구 개수가 적을수록 Claude가 어떤 도구를 골라야 할지 헷갈릴 여지가 줄어들기 때문입니다.
도구 응답(tool_result)은 어떻게 설계해야 하나요?
도구가 돌려주는 결과에는 Claude가 다음 판단에 실제로 필요한 정보만 담아야 합니다. 공식 문서는 내부 시스템에서만 통하는 불투명한 참조값 대신, 슬러그(slug, 사람이 읽을 수 있는 짧은 식별자)나 UUID처럼 의미가 통하는 안정적인 식별자를 돌려주라고 안내합니다. 필요 없는 필드까지 잔뜩 담긴 응답은 컨텍스트(대화가 참고하는 정보 범위)를 낭비하고, Claude가 정작 필요한 값을 찾기 어렵게 만듭니다.
자주 하는 실수와 해결 방법
도구를 처음 등록할 때 막히기 쉬운 지점을 정리했습니다.
- 증상: API가 400 에러로 요청을 거부한다. 원인: 이름에 공백·마침표·한글 등 정규식이 허용하지 않는 문자가 들어갔을 가능성이 큽니다. 조치: 이름을 영문 소문자와 밑줄(_)만으로 다시 지어
^[a-zA-Z0-9_-]{1,64}$규칙을 다시 확인하세요. - 증상: Claude가 도구를 써야 할 상황인데도 텍스트로만 답한다. 원인: 설명이 너무 짧아 Claude가 이 요청이 도구 사용 대상인지 판단하지 못했을 가능성이 있습니다. 조치: 설명에 "언제 사용해야 하는지"를 명시적으로 추가하고, 필요하면 시스템 프롬프트에 "도구를 먼저 확인한 뒤 답하라" 같은 안내를 더하세요.
- 증상: 비슷한 이름의 도구 중 엉뚱한 것을 호출한다. 원인: 도구가 많아지면서 이름만으로 구분이 안 되는 상태입니다. 조치: 서비스명을 접두사로 붙이는 네임스페이스 규칙(
서비스_동작_대상)으로 이름을 통일하세요.
자주 묻는 질문
Q. 도구 이름에 한글을 써도 되나요?
안 됩니다. 공식 정규식 규칙(^[a-zA-Z0-9_-]{1,64}$)은 영문 대소문자, 숫자, 밑줄, 하이픈만 허용하므로 한글이나 공백이 들어가면 요청이 거부됩니다.
Q. 설명은 무조건 길게 쓸수록 좋은가요?
길이 자체가 목적은 아니고, 무엇을·언제·파라미터 의미·한계라는 네 가지 정보가 빠짐없이 담기는 게 목적입니다. 공식 문서는 도구당 최소 3~4문장을 권장하며, 도구가 복잡할수록 더 길어져도 된다고 안내합니다.
Q. 도구를 몇 개까지 등록할 수 있나요?
근거 자료에 구체적인 개수 제한은 나와 있지 않습니다. 다만 도구가 많아질수록 이름 충돌과 설명 모호성으로 오작동 가능성이 커지므로, 비슷한 동작은 action 파라미터로 묶고 네임스페이스로 정리하는 편이 안전합니다.
이름은 정규식 규칙과 네임스페이스로, 설명은 무엇을·언제·파라미터·한계 네 가지로 채운다는 원칙만 지켜도 도구 오작동의 상당 부분을 줄일 수 있습니다. 이미 등록해 둔 도구가 있다면 이 글의 체크리스트로 하나씩 다시 점검해 보세요.