AI 에이전트의 도구 정의 설계 원칙: 스키마·명명·응답 실전 가이드

이 기사에서 알 수 있는 것

• AI 에이전트의 도구 정의 (JSON Schema)를 설계하기 위한 7가지 원칙
• 명명·설명문·파라미터 설계의 구체적인 베스트 프랙티스 (Best Practices)
• 응답 설계로 토큰 소비를 60% 이상 절감하는 수법
• 대규모 도구 세트 (30개 이상)에서도 정밀도를 유지하는 Tool Search·동적 발견 메커니즘
• Anthropic Claude·OpenAI 양측의 공식 가이드라인에 기반한 2026년 시점의 권장 사항

대상 독자

상정 독자: AI 에이전트를 개발·운용하는 중급 이상의 엔지니어 -
필요한 전제 지식:

• LLM의 Function Calling / Tool Use의 기본 개념
• JSON Schema의 기초 (type, properties, required의 의미)
• Python 또는 TypeScript의 기초 문법

결론·성과

도구 정의의 품질은 에이전트 전체의 성능을 좌우하는 최대 레버리지 포인트입니다. Anthropic의 공식 가이드라인에 따르면, 설명문을 3-4문장 이상으로 충실하게 작성하는 것만으로도 도구 선택의 정밀도가 대폭 향상되며, input_examples를 추가함으로써 복잡한 파라미터의 정확한 지정률이 72%에서 90%로 개선되었다고 보고되었습니다. 나아가 응답 설계의 최적화에서는 상세/간결 전환 파라미터 도입을 통해 토큰 소비를 206토큰에서 72토큰으로 약 65% 절감한 사례가 있습니다.

본 기사에서는 Anthropic·OpenAI 양측의 2026년 시점 공식 문서와 엔지니어링 블로그를 바탕으로, 도구 정의 설계의 7가지 원칙을 체계적으로 해설합니다.

도구 정의가 중요한 이유를 이해하기

AI 에이전트가 도구를 사용하는 흐름은 「도구 정의 읽기 → 호출 판단 → 인자 생성 → 결과 해석」이라는 4단계로 구성됩니다. 이 중 첫 번째인 「도구 정의 읽기」가 모든 정밀도를 결정합니다.

Anthropic의 엔지니어링 블로그 「Writing tools for agents」에서는 도구 정의 설계에 대해 다음과 같이 언급하고 있습니다. "모호한 프롬프트와 약한 도구 스키마는 모델의 품질 그 자체보다 운영 환경에서의 장애를 더 많이 일으킨다". 즉, 아무리 고성능의 LLM을 사용하더라도 도구 정의 설계가 불충분하면 에이전트는 올바르게 동작하지 않습니다.

이하에서는 도구 정의를 구성하는 4가지 요소(명명·설명문·파라미터·응답) 각각의 설계 원칙을 해설합니다.

원칙 1~2: 명명과 설명문을 설계하기

원칙 1: 의미 있는 네임스페이스로 명명하기

도구 이름은 LLM이 가장 먼저 접하는 식별자입니다. 이름만으로도 「무엇을 하는 도구인가」를 알 수 있도록 설계합니다.

명명 규칙:

여러 서비스의 도구를 제공하는 경우, 네임스페이스(접두사)의 일관성이 도구 선택 정밀도와 직결됩니다. Anthropic의 가이드라인에서는 "서비스나 리소스를 가로지르는 도구에는 접두사를 붙여라"라고 명시되어 있습니다.

from pydantic import BaseModel, Field
class GitHubListPRs(BaseModel):
    """github_list_prs 도구의 파라미터 정의"""
    ...

흔한 실수: 도구 이름을 data나 process와 같은 범용적인 동사로 설정하면, 여러 도구가 있는 환경에서 LLM이 올바른 도구를 선택할 수 없게 됩니다. 도구 수가 20개를 넘어가면 이 문제는 더욱 두드러집니다.

원칙 2: 설명문은 3-4문장 이상으로 작성하기

Anthropic의 공식 문서에서는 도구 설명문에 대해 "이것이 도구 성능에 있어 가장 중요한 요소"라고 명언하고 있습니다. 설명문에는 다음 5가지 사항을 포함해야 합니다.

• 무엇을 하는가 (What it does): 도구의 기능
• 언제 사용하는가 (When to use): 사용해야 하는 상황
• 언제 사용하지 않는가 (When not to use): 다른 도구를 사용해야 하는 상황
• 무엇을 반환하는가 (What it returns): 응답 (Response)의 내용
• 제약 사항 및 주의점 (Constraints/Notes): 알려진 제한 사항

{
"name": "get_stock_price",
"description": "지정된 티커 심볼(Ticker Symbol)의 현재 주가를 가져옵니다. 티커 심볼은 NYSE 또는 NASDAQ에 상장된 기업의 유효한 심볼이어야 합니다. 최신 거래 가격을 USD로 반환합니다. 사용자가 특정 주식의 현재 가격 또는 최신 가격에 대해 질문했을 때 사용하십시오. 주가 이외의 기업 정보(재무제표, 뉴스 등)는 이 도구로 가져올 수 없습니다."
...
}

다음은 나쁜 예시입니다.

{
"name": "get_stock_price",
"description": "주가를 가져옵니다"
...
}

이 차이는 실제 에이전트 성능과 직결됩니다. 모호한 설명문은 LLM이 "이 도구로 기업의 결산 정보도 가져올 수 있는 것 아닌가"라고 오해하여 도구를 호출하게 만들고, 기대와 다른 결과를 받아 불필요한 재시도 (Retry)가 발생하게 합니다.

이 접근 방식에서의 주의점은 설명문을 너무 길게 작성하면 토큰 소비가 증가한다는 것입니다. 도구당 100~200 토큰 정도가 기준입니다. 도구 수가 많을 경우, 후술할 Tool Search와 조합하여 필요한 도구만 동적으로 로드하는 설계를 검토하십시오.

원칙 3~4: 파라미터 스키마 (Parameter Schema)를 설계한다

원칙 3: enum 제약과 required/optional을 엄격하게 정의한다

파라미터 설계에서는 "부정 상태를 표현 불가능하게 만들기 (Make invalid states unrepresentable)"라는 원칙이 중요합니다. 자유 텍스트 대신 enum 제약을 사용하고, 필수 (Required)와 선택 (Optional)을 명확하게 분리합니다.

enum 제약의 효과:

{
"name": "search_products",
"input_schema": {
...
}
}

strict mode 활용:

OpenAI와 Anthropic 모두에서 strict: true를 설정하면 LLM의 출력이 스키마에 엄격하게 준수됩니다. strict mode를 활성화하려면 다음 요구 사항을 충족해야 합니다.

{
"name": "create_calendar_event",
"strict": true,
...
}

원칙 4: input_examples로 구체적인 예를 보여준다

JSON Schema만으로는 다 전달할 수 없는 패턴 (선택적 파라미터의 조합, 포맷 관습 등)은 input_examples로 보완합니다. Anthropic의 보고에 따르면, input_examples를 추가함으로써 복잡한 파라미터의 정확한 지정률이 72%에서 90%로 개선되었습니다.

{
"name": "search_flights",
"description": "지정된 조건으로 항공편을 검색합니다. 출발지 및 목적지는 공항 코드 (IATA)로 지정하십시오. 편도와 왕복 모두 지원합니다.",
...
}

두 번째 예시에서는 선택적 파라미터 (return_date, passengers)를 생략하여, 편도 검색 패턴을 LLM이 학습할 수 있도록 하고 있습니다.

주의점: input_examples는 하나당 2050 토큰 (단순한 경우)에서 100200 토큰 (복잡한 중첩이 있는 경우)을 소비합니다. 3~5개의 예시가 권장되며, 과도하게 추가하면 컨텍스트 윈도우 (Context Window)를 압박하게 됩니다.

원칙 5: 응답 (Response)을 설계한다

고신호 정보만 반환한다

도구의 응답 설계는 에이전트의 추론 정확도와 토큰 효율성 모두에 영향을 미칩니다. Anthropic의 "Writing tools for agents"에서는 "의미 있는 컨텍스트 정보를 우선시하고, LLM이 다음 단계를 판단하는 데 필요한 필드만 반환하라"고 권장합니다.

설계 포인트:

• 안정적인 식별자 반환: 내부 ID가 아닌 슬러그(Slug)나 UUID와 같이 의미 있는 식별자 사용
• 불필요한 필드 제외: API의 로우 데이터(Raw response)를 그대로 반환하지 말 것
• 페이지네이션(Pagination) 및 필터링(Filtering): 결과가 많을 경우 개수 제한과 페이지네이션 적용
• 상세도 전환: detail_level 파라미터를 통해 상세/간결 모드를 선택할 수 있도록 설계

from typing import Literal
from pydantic import BaseModel, Field
class SlackSearchParams(BaseModel):
...

Anthropic의 엔지니어링 블로그에서는 Slack 도구의 사례로 detail_level 파라미터를 도입함으로써, 메시지 1개당 토큰 소비량을 206토큰에서 72토큰으로 약 65% 절감했다고 보고했습니다. 에이전트가 처음에 concise로 개요를 파악하고, 필요에 따라 detailed로 심층 분석하는 2단계 접근 방식이 유효합니다.

흔한 실수: API의 로우 데이터(Raw response)를 도구 결과로 그대로 반환하는 패턴입니다. 예를 들어 GitHub API의 PR(Pull Request) 정보에는 수십 개의 필드가 포함되어 있지만, 에이전트가 다음 행동을 판단하는 데 필요한 것은 title, state, author, url 정도입니다.

def format_pr_response_concise(pr: dict) -> dict:
    """에이전트를 위해 고신호(High-signal) 필드만 추출"""
    return {
...

응답이 너무 클 경우의 대처법으로, 데이터를 잘라낼(Truncation) 때는 가이드 메시지를 포함할 것을 권장합니다. 예:

"결과가 너무 많습니다 (전체 200건 중 상위 10건 표시). 더 구체적인 키워드로 다시 검색해 주세요."

원칙 6: 도구를 통합하라

관련 작업을 하나의 도구로 묶기

Anthropic의 공식 문서에서는 "개별 작업마다 별도의 도구를 만드는 대신, 전략적으로 통합하라"고 권장합니다. 구체적으로는 create_pr, review_pr, merge_pr를 3개의 별도 도구로 제공하는 것이 아니라, action 파라미터를 가진 하나의 github_pr 도구로 통합하는 접근 방식입니다.

통합 전:

도구 수: 3
- create_pr(repo, title, body, base, head)
- review_pr(repo, pr_number, action, body)
...

통합 후:

{
"name": "github_pr",
"description": "GitHub Pull Request의 생성, 리뷰, 머지를 수행합니다. action 파라미터로 작업을 지정하세요. create인 경우 title/body/base/head가 필수, review인 경우 pr_number/review_action이 필수, merge인 경우 pr_number가 필수입니다.",
...
}

통합의 장점:

• LLM이 선택해야 할 도구 수가 줄어들어 선택 정확도가 향상됨
• 관련 작업의 컨텍스트(Context)를 LLM이 한곳에서 파악할 수 있음
• 도구 정의 전체의 토큰 소비가 절감됨

통합해서는 안 되는 경우:

• 작업의 성격이 완전히 다른 경우 (예: 이메일 전송과 날씨 조회)
• 통합으로 인해 파라미터가 너무 복잡해지는 경우
• 권한 수준이 다른 작업을 혼합하여 보안 리스크가 발생하는 경우

도구 통합의 판단 기준으로, "동일한 리소스에 대한 서로 다른 작업"이라면 통합을 검토하고, "서로 다른 리소스에 대한 작업"이라면 분리를 유지하는 것이 기준입니다.

원칙 7: 대규모 도구 세트를 관리하라

Tool Search를 통한 동적 발견

도구 수가 늘어날수록 LLM의 선택 정확도는 저하됩니다. OpenAI의 가이드라인에서는 "20개 이하의 도구로 초기 정확도를 확보"할 것을, Composio의 테스트에서는 "30개 초과 시 정확도가 79.5%까지 저하"된다고 보고했습니다.

이 문제에 대한 Anthropic의 해결책이 바로 Tool Search (defer_loading: true)입니다. 도구 정의를 사전에 모두 로드하는 것이 아니라, LLM이 필요에 따라 검색하고 발견하는 메커니즘입니다.

효과:

Anthropic의 공식 가이드라인에 따르면, 도구 검색 (Tool Search)의 도입은 다음과 같은 조건에서 특히 효과적입니다.

• 도구 정의 전체가 10,000 토큰을 초과하는 경우
• 도구 선택 (Tool Selection)의 정확도에 문제가 있는 경우
• MCP 서버를 여러 개 연결하고 있는 경우

구현 예시 (Claude API):

import anthropic
client = anthropic.Anthropic()
tools = [
...

MCP (Model Context Protocol)를 통한 도구 표준화

2026년 현재, 도구 연결의 표준화로서 Anthropic이 책정한 **MCP (Model Context Protocol)**의 보급이 진행되고 있습니다. MCP는 3가지 프리미티브 (Primitives)로 구성됩니다.

MCP를 채택함으로써 도구 정의를 하나의 MCP 서버로 구현하면, Claude Code, Cursor, VS Code 등 여러 AI 클라이언트에서 동일한 도구를 이용할 수 있습니다. 통신에는 JSON-RPC 2.0을 사용하며, 로컬 프로세스 (stdio)와 원격 서버 (HTTP/SSE)를 모두 지원합니다.

2026년 7월 28일에 릴리스 후보가 공개되는 최신 사양에서는 상태가 없는 (Stateless) HTTP 기반 설계, 서버 렌더링 UI 제공 (MCP Apps 확장), OAuth/OpenID Connect를 준수하는 인가 (Authorization) 등 실운영을 고려한 기능들이 추가되었습니다.

제약 사항: MCP는 아직 사양 책정 단계에 있으며, 2026년 7월 최종 사양 공개 전까지는 API의 파괴적 변경 (Breaking Changes)이 발생할 가능성이 있습니다. 프로덕션 도입을 검토하는 경우에는 사양의 버전을 고정하여 운용하는 것을 권장합니다.

자주 발생하는 문제와 해결 방법

도구 설계 시 자주 마주치는 문제와 그 해결책을 정리합니다.

에러 메시지 설계

도구 실행이 실패했을 경우, LLM이 다음 행동을 판단할 수 있는 에러 메시지를 반환하는 것이 중요합니다.

def handle_tool_error(error: Exception, tool_name: str) -> dict:
    """에이전트용 실행 가능한 에러 응답"""
    if isinstance(error, ValueError):
        ...

요약 및 다음 단계

요약:

원칙 1: 명명 (Naming)— 서비스명 접두사(Prefix) + 동사 + 대상을 사용하여 고유하게 식별할 수 있는 이름을 붙인다 -
원칙 2: 설명문 (Description)— 3~4문장 이상으로 「무엇을」, 「언제」, 「언제 사용하지 않는지」, 「무엇을 반환하는지」, 「제약 사항」을 기술한다 -
원칙 3: 파라미터 (Parameters)— enum 제약, required/optional 명시, strict mode를 통해 부정확한 상태를 배제한다 -
원칙 4: 구체적 예시 (Examples)— input_examples를 통해 임의 파라미터의 조합 패턴을 LLM에 학습시킨다 -
원칙 5: 응답 (Response)— 고신호(High-signal) 필드만 반환하며, detail_level 파라미터로 토큰 소비를 제어한다 -
원칙 6: 통합 (Integration)— 동일 리소스에 대한 조작은 action 파라미터를 사용하여 하나의 도구로 통합한다 -
원칙 7: 확장성 (Scale)— 도구가 20개를 초과할 경우, Tool Search (defer_loading)를 통해 동적 발견(Dynamic Discovery) 방식으로 전환한다

다음에 해야 할 일:

• 기존의 도구 정의를 본 기사의 7가지 원칙에 비추어 감사(Audit)하고, 설명문의 충실도를 확인한다
• strict mode를 활성화하여 파라미터의 유효성 검사(Validation) 정밀도를 검증한다
• 도구 수가 10개를 초과하는 경우, Tool Search 또는 MCP 서버 도입을 계획한다

참고

• Anthropic: Define tools (공식 문서)
• Anthropic: Writing tools for agents (엔지니어링 블로그)
• Anthropic: Introducing advanced tool use (엔지니어링 블로그)
• OpenAI: Function calling guide (공식 문서)
• Complete Guide to LLM Function Calling (youngju.dev)
• Tool Calling Explained: The Core of AI Agents (Composio)
• MCP 2026 Roadmap (Model Context Protocol Blog)

Discussion