핵심 정리
| 필드 | 역할 |
|---|---|
name | tool 식별자, 짧고 명확한 이름 |
description | 언제 쓰고 언제 쓰지 않을지 설명 |
input_schema | tool 입력 JSON Schema |
input_examples | 복잡한 입력 예시 보강 |
tool_choice | 자동 선택, 강제 사용, 금지 제어 |
strict | 입력 schema 준수 강화 |
{
"name": "github_list_prs",
"description": "List pull requests for a repository. Use this when the user asks for open review targets or PR metadata. Do not use it to merge or edit pull requests.",
"input_schema": {
"type": "object",
"properties": {
"repo": { "type": "string" },
"state": { "type": "string", "enum": ["open", "closed", "all"] }
},
"required": ["repo"]
}
}구조
Tool definition은 단순한 함수 목록이 아니라 Claude가 어떤 행동을 선택할지 판단하는 인터페이스입니다. schema만 정확하고 description이 짧으면, Claude는 tool을 언제 써야 하는지 충분히 알기 어렵습니다.
좋은 tool 정의
-> 무엇을 하는가
-> 언제 써야 하는가
-> 언제 쓰면 안 되는가
-> 입력 필드가 결과에 어떤 영향을 주는가
-> 반환값의 한계가 무엇인가tool이 너무 잘게 나뉘면 선택지가 많아져 selection ambiguity가 생깁니다. create_pr, review_pr, merge_pr처럼 가까운 작업은 하나의 namespace나 action 필드로 묶는 편이 더 안정적인 경우가 많습니다.
반대로 하나의 tool이 모든 일을 하게 만들면 schema와 permission 경계가 흐려집니다. 외부 side effect가 있는 작업은 읽기용 tool과 쓰기용 tool을 분리해 승인 흐름을 명확히 하는 편이 안전합니다.
선택 기준
| 상황 | 선택 |
|---|---|
| Claude가 필요할 때만 tool을 고르게 함 | tool_choice: auto |
| 반드시 tool 중 하나를 쓰게 함 | tool_choice: any |
| 특정 tool만 강제 | tool_choice: tool |
| tool 호출 없이 답변 | tool_choice: none |
| 입력 구조가 복잡함 | input_examples 추가 |
| 잘못된 입력이 위험함 | strict와 서버 검증 병행 |
| tool 응답이 너무 큼 | 의미 있는 식별자와 필요한 필드만 반환 |
tool_choice를 바꾸면 prompt caching의 message cache가 무효화될 수 있습니다. tool 정의와 system prompt는 안정적으로 유지하고, 선택 방식은 요청 목적에 맞춰 최소한으로 바꾸는 편이 좋습니다.
주의할 점
Tool schema는 보안 경계가 아닙니다. Claude가 올바른 입력을 만들도록 돕는 계약이지만, 실제 권한 확인과 데이터 검증은 tool 서버 쪽에서 다시 수행해야 합니다.
또 tool 응답을 과하게 크게 만들면 다음 reasoning 단계가 불안정해지고 context를 빠르게 소모합니다. 원본 전체보다 안정적인 ID, 요약, 다음 행동에 필요한 필드를 우선 반환하세요.
참고 링크
1 sources