Quick Reference

Tool definition은 Claude가 함수 호출을 만들기 위한 설명·입력 계약이지, 외부 시스템의 권한 경계가 아닙니다. 읽기와 쓰기, 되돌릴 수 있는 작업과 되돌릴 수 없는 작업을 분리하고, description에 사용 조건·제한·결과를 적은 뒤 input_schema를 좁게 만듭니다. 위험한 실행은 schema가 맞아도 서버가 다시 인가합니다.

{
  "name": "get_order",
  "description": "현재 사용자가 접근 가능한 주문 한 건을 읽습니다. 주문을 변경하지 않으며, 존재하지 않거나 권한이 없으면 오류 코드를 반환합니다.",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string", "description": "조회할 주문 ID" }
    },
    "required": ["orderId"],
    "additionalProperties": false
  }
}

정의를 나누는 기준

좋은 description은 기능 이름을 풀어 쓰는 데서 끝나지 않습니다. 언제 이 도구를 선택하는지, 언제 선택하지 않는지, 각 입력이 결과에 어떤 영향을 주는지, 반환값에서 보장하지 않는 것을 적습니다. Schema가 맞아도 description이 빈약하면 Claude는 비슷한 도구 중 무엇을 쓸지 잘못 고를 수 있습니다.

읽기와 쓰기는 보통 다른 도구로 둡니다. get_order와 cancel_order를 하나의 order(action)으로 합치면 tool 수는 줄지만, description·권한·감사·재시도 정책이 섞입니다. 반대로 같은 권한과 실패 정책을 공유하는 매우 작은 읽기 도구가 여럿이면 필터·ID·상태 같은 입력을 가진 하나의 조회 도구가 선택 혼동을 줄일 수 있습니다.

호출과 결과 처리

클라이언트 도구에서 Claude가 stop_reason: "tool_use"와 tool_use content block을 반환하면, 호출자는 id, name, input을 읽어 실제 도구를 실행합니다. 그 결과는 같은 도구 사용 ID를 가진 tool_result block으로 다음 user message에 돌려보냅니다. 도구가 성공했다고 텍스트로만 알려 주거나 ID를 빼면 대화가 끊기거나 결과를 잘못 연결할 수 있습니다.

for block in response.content:
    if block.type != "tool_use":
        continue

    result = run_as_current_user(block.name, block.input)
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": block.id,
        "content": json.dumps(result),
    })

messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})

strict: true는 지원 모델에서 도구 이름과 input을 schema에 맞추도록 제약합니다. 일반 schema보다 호출 형식 오류를 줄이지만, 권한 없는 주문 ID를 추측하지 못하게 하거나 중복 결제를 막아 주지는 않습니다. 사용자의 identity, tenant, resource ownership, rate limit, idempotency key, timeout은 도구 서버가 처리합니다.

자주 틀리는 부분

권장 실행 순서
1. tool input의 schema·길이·형식을 검사한다.
2. 현재 사용자와 대상 resource의 권한을 서버에서 확인한다.
3. 쓰기 작업에는 idempotency와 감사 로그를 둔다.
4. 성공·실패·권한 거부를 구조화한 tool_result로 반환한다.
5. 모델의 최종 문장은 실행 로그가 아니라 사용자용 설명으로 취급한다.