tool description은 AI 에이전트가 어떤 도구를 언제 호출할지 판단할 때 참고하는 설명입니다. 그래서 길게 쓰면 더 좋아 보이지만, 실제로 중요한 것은 길이 자체가 아니라 도구의 경계가 선명한가입니다.
핵심은 모델이 이 도구를 써야 하는 상황과 쓰면 안 되는 상황을 구분할 수 있게 만드는 것입니다. 설명이 길어도 호출 조건, 입력 schema, 실패 조건이 흐리면 잘못된 tool selection이 생길 수 있습니다.
tool description은 무엇을 설명해야 할까
도구 설명은 단순 기능 소개문이 아닙니다. 에이전트 입장에서는 여러 후보 중 하나를 고르는 판단 기준입니다. 따라서 이 도구가 무엇을 하는지뿐 아니라, 어떤 입력을 받을 때 적합한지까지 알려줘야 합니다.
- 도구의 목적
- 호출해야 하는 상황
- 호출하지 말아야 하는 상황
- 필수 입력과 선택 입력의 의미
- 실패하거나 빈 결과가 나올 수 있는 조건
길면 무조건 좋은가
길이가 도움이 되는 경우는 있습니다. 비슷한 도구가 많거나, 같은 단어가 여러 의미로 쓰이거나, 호출 금지 조건이 중요한 도구라면 설명을 넉넉히 써야 합니다.
하지만 길게 쓴 설명이 같은 말을 반복하거나, 파라미터 설명과 충돌하거나, 도구 범위를 넓게 부풀리면 오히려 선택 품질이 떨어질 수 있습니다. tool description은 짧은 광고문보다 운영 규격에 가까워야 합니다.
schema가 description보다 먼저 흔들리는 경우
도구 선택 문제는 description만의 문제가 아닙니다. 파라미터 이름이 모호하거나 required 필드가 제대로 잡히지 않으면 모델은 도구를 골라도 잘못된 인자를 만들 수 있습니다.
{
"name": "search_posts",
"description": "Search published blog posts by keyword. Use this only when the user asks for existing posts or internal links.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search keyword, title fragment, or topic."
},
"limit": {
"type": "integer",
"description": "Maximum number of posts to return."
}
},
"required": ["query"]
}
}좋은 tool description의 형태
- 첫 문장에 도구의 실제 작업을 쓴다
- 비슷한 도구와의 차이를 한 문장으로 적는다
- 부작용이 있는 도구는 쓰기 전 승인 조건을 명시한다
- 읽기 전용 도구와 쓰기 도구를 분리한다
- 예상 출력과 빈 결과 가능성을 알려준다
나쁜 설명의 흔한 패턴
가장 나쁜 설명은 ‘무엇이든 처리한다’는 식의 설명입니다. 모델은 넓은 설명을 보면 해당 도구를 과하게 선택할 수 있습니다. 반대로 너무 짧아서 경계가 없는 설명도 비슷한 문제를 만듭니다.
- Manage data
- Use this for user requests
- Search or update anything
- Helpful tool for documents
- Do the task
MCP와 많은 도구 환경에서 더 중요해지는 이유
에이전트가 연결할 수 있는 도구가 많아질수록 description 품질은 더 중요해집니다. 도구 이름만으로는 충분하지 않고, 도구별 권한, 대상 데이터, 읽기/쓰기 여부가 설명에 드러나야 합니다.
도구 수가 많고 schema가 커지면 모든 도구를 매번 context에 넣는 것도 비용과 정확도 측면에서 부담입니다. 이런 환경에서는 자주 쓰는 도구와 나중에 불러올 도구를 나누는 설계도 함께 봐야 합니다.
실무 체크리스트
- 비슷한 도구 2개를 나란히 놓고 차이가 설명되는지 본다
- description과 parameter description이 서로 충돌하지 않는지 확인한다
- 부작용 있는 도구에는 승인 조건을 쓴다
- 도구가 실패했을 때 모델이 다음 행동을 알 수 있게 한다
- 실제 로그에서 잘못 호출된 사례를 모아 설명을 줄이거나 고친다
정리
tool description은 길수록 좋은 문장이 아니라, 도구 선택을 안정화하는 작은 명세입니다. 길이는 필요한 만큼만 쓰되, 호출 조건과 금지 조건, schema 의미를 분명히 해야 합니다.
공식적인 tool calling 흐름은 OpenAI function calling 문서에서 확인할 수 있습니다. MCP 맥락은 MCP 입문 글과 함께 보면 좋습니다.
