현장에서 에이전트 PoC를 열어보면 같은 장면이 반복된다. 모델은 똑똑한데 도구 선택이 흔들린다. 조회 도구를 써야 할 때 수정 도구를 고르고, 고객 ID를 넣어야 할 칸에 고객명을 넣고, 실패 결과를 다시 같은 방식으로 호출한다. 이 문제를 모델 성능 탓으로 돌리면 개선이 늦어진다. 원인은 대개 툴 스키마다.
OpenAI는 function tool을 JSON Schema로 정의하고, strict mode에서 스키마 준수를 강화한다고 문서화한다. Gemini API도 function declaration의 name, description, parameters를 모델이 도구 선택에 쓰는 정보로 설명한다. MCP 역시 Tool에 name, description, inputSchema, outputSchema를 둔다. 세 플랫폼의 표현은 달라도 결론은 같다. 에이전트는 도구를 실행하기 전에 스키마를 읽고 판단한다. (platform.openai.com)
스키마는 API 명세가 아니라 선택 장치다
사람용 API 문서는 길수록 친절하다. 에이전트용 툴 스키마는 다르다. 모델은 전체 후보 도구 중에서 지금 필요한 하나를 골라야 한다. 그래서 description은 기능 설명이 아니라 선택 기준이어야 한다.
나쁜 설명은 “고객 정보를 조회한다”다. 좋은 설명은 “고객 ID가 확정된 경우에만 CRM의 기본 프로필을 조회한다. 이름, 전화번호, 이메일 검색에는 쓰지 않는다”다. 후자는 사용 조건과 금지 조건을 동시에 준다.
툴 스키마의 1차 목적은 실행 성공이 아니라 오선택 방지다.
이 관점이 없으면 비슷한 도구가 늘어날수록 에이전트 품질은 떨어진다. get_customer, search_customer, lookup_customer_profile 같은 이름이 함께 있으면 모델은 의미 차이를 추론한다. 운영 시스템에서 추론은 설계 실패다.
이름·설명·파라미터가 한 문장처럼 맞아야 한다
툴 스키마는 세 겹으로 읽힌다. name은 빠른 분류, description은 사용 판단, parameters는 실행 제약이다. 셋이 다른 말을 하면 모델은 가장 익숙한 단어를 따라간다.
| 설계 항목 | 흔한 실패 | 운영형 설계 |
|---|---|---|
| name | update_data처럼 범용 동사 사용 |
update_customer_shipping_address처럼 대상과 행위를 고정 |
| description | 가능한 기능을 모두 나열 | 언제 쓰고 언제 쓰지 않는지 명시 |
| parameter | query: string 하나로 받음 |
customer_id, address_type, effective_date처럼 의미 단위 분리 |
| enum | 설명문에 “A/B/C 중 하나”라고 씀 | enum으로 허용값을 제한 |
| output | 자유 텍스트 반환 | 후속 판단에 필요한 상태값을 구조화 |
Gemini 문서는 enum을 설명문에 적는 대신 스키마에 넣으라고 안내한다. OpenAI strict mode는 객체의 추가 속성을 막고 필요한 필드를 명시하는 방식으로 스키마 준수를 강화한다. MCP 2025-11-25 스키마도 outputSchema와 structuredContent를 통해 결과 구조를 별도로 다룬다. 이 변화는 한 방향을 가리킨다. 자연어 설명으로 버티던 도구 설계가 타입과 제약 중심으로 이동하고 있다. (ai.google.dev)
도구가 많아지면 하네스가 필요하다
툴 스키마만 잘 써도 초반 품질은 오른다. 그러나 운영 환경에서는 도구 수가 늘고 권한이 갈라지고 사용자 의도가 섞인다. 이때는 스키마 설계를 하네스 엔지니어링으로 확장해야 한다.
첫째, 도구를 업무 단계별로 묶는다. 상담 시작, 본인 확인, 조회, 변경, 이력 기록 도구를 한꺼번에 노출하지 않는다.
둘째, 읽기 도구와 쓰기 도구를 분리한다. MCP의 ToolAnnotations에는 readOnlyHint, destructiveHint, idempotentHint 같은 힌트가 있지만, MCP 문서는 이 힌트만으로 신뢰 결정을 해서는 안 된다고 못박는다. 권한과 승인 흐름은 애플리케이션 레벨에서 막아야 한다. (modelcontextprotocol.io)
셋째, 실패 결과를 구조화한다. “실패했습니다”는 에이전트에게 다음 행동을 주지 않는다. error_code, retryable, missing_fields, user_confirmation_required를 반환해야 다음 턴이 안정된다.
운영 전 검수표가 품질을 만든다
툴 스키마 검수는 개발 완료 후 문구를 다듬는 일이 아니다. 에이전트 제품 설계의 중심 작업이다. 배포 전에 다음 네 가지를 본다.
- 같은 의도에 반응하는 도구가 중복되지 않는가.
- description에 사용 조건과 금지 조건이 함께 있는가.
- 파라미터가 업무 의미 단위로 쪼개져 있는가.
- 실행 결과가 다음 판단에 필요한 구조를 갖는가.
AX Ops에서는 이 검수를 프롬프트 리뷰가 아니라 운영 설계 리뷰로 다룬다. 도구 선택 로그, 실패 코드, 승인 흐름, 재시도 정책을 함께 본다. 그래야 에이전트가 데모에서는 되고 현장에서는 흔들리는 문제를 줄인다.
참고
- OpenAI, Function calling guide, 2026 확인: https://developers.openai.com/api/docs/guides/function-calling
- Google AI for Developers, Function calling with the Gemini API, last updated 2025-12-18: https://ai.google.dev/gemini-api/docs/function-calling
- Model Context Protocol, Schema Reference 2025-11-25: https://modelcontextprotocol.io/specification/2025-11-25/schema
- Anthropic Claude API Reference, Messages tools schema, 2026 확인: https://platform.claude.com/docs/en/api/messages
툴 스키마를 바로잡는 일은 작은 문서 정리가 아니라 에이전트 운영 품질을 결정하는 설계 작업이다. 에이전트 제품을 운영까지 가져가려면 AX Ops 방법론 →에서 시작하면 된다.