에이전트에서는 docstring이 코드다

일반 코드에서 docstring은 사람을 위한 설명입니다. 주석과 달리 __doc__ 에 남아 help() 나 IDE 툴팁에 뜨지만, 쓰임은 딱 거기까지입니다. 바쁘면 생략하고, 시그니처만 봐도 알 만하면 한 줄로 끝내는 경우가 많습니다.

하지만 에이전트가 부르는 도구에서는 다릅니다. docstring이 모델이 보는 인터페이스의 전부입니다.

함수 본문은 모델에게 가지 않습니다

Model 과 docstring

API 필드 이름은 description 입니다. Python SDK 는 함수의 docstring 을 그 필드에 그대로 넣고, Args: 절을 파라미터 설명으로 씁니다.

도구를 등록하면 모델에게 전달되는 것은 이름과 파라미터 스키마와 이 설명뿐입니다. 함수 본문은 안 갑니다. 즉 모델 입장에서 이 도구가 무엇을 하는지 알 방법은 docstring 하나뿐입니다.

공식 문서도 같은 말을 합니다. Tool use with Claude 첫 문단은 이렇게 시작합니다.

Claude determines when to call a tool based on the user’s request and the tool’s description.

구현을 아무리 정확히 짜도, docstring이 “데이터를 조회합니다” 수준이면 모델은 언제 이 도구를 불러야 하는지 알 수 없습니다. 부르지 않거나, 엉뚱한 자리에서 부를 수 있습니다.

이 문제가 고약한 건 에러가 안 난다는 점입니다. 도구를 안 부르면 모델은 그냥 아는 대로 답합니다. 로그에는 실패가 남지 않습니다. 사용자만 “왜 이건 안 찾아보지” 하고 불편을 느낍니다.

그래서 도구를 추가한 뒤에는 모델이 그 도구를 실제로 불렀는지를 따로 확인해야 합니다. 호출 로그에 도구 이름이 안 보이면 구현이 아니라 설명을 의심해야 합니다.

시그니처가 이미 말하는 것은 빼고, 시그니처가 말 못 하는 것을 적습니다.

“무엇을 못 하는가”가 특히 중요합니다. 모델은 도구가 만능이라고 가정하고 부릅니다. 한계를 안 적으면 빈 결과를 받고 나서 스스로 지어냅니다.

네 항목을 실제로 어떻게 쓰는지는 docstring 작성 가이드에서 공식 지침과 예시로 다뤘습니다.

코드 리뷰에서 docstring은 보통 “있으면 좋고” 항목입니다. 에이전트 도구에서는 시그니처 변경과 같은 급으로 봅니다. 인자를 하나 추가하고 docstring을 안 고치면, 모델은 새 인자를 인식하지 못하고 계속 예전 방식을 유지합니다.

동작이 바뀌었는데 설명이 그대로면 그건 깨진 인터페이스입니다.