게시일: 2026년 5월 18일
WebMCP 도구 선언은 개발자나 에이전트가 출력을 확인하고 다시 시도할 필요 없이 명확해야 합니다. 명령형 API 또는 선언형 API를 사용하는 경우 다음 권장사항을 따르세요.
- 빌드하기 전에 도구 전략을 만드세요.
- 명확한 표현과 시맨틱 HTML을 사용하세요.
- 스키마를 설계하고 입력을 처리하세요.
- 안정적인 도구를 빌드하세요.
- 테스트 및 디버그하세요.
보안을 고려한 도구 만들기에 관해 별도로 작성했습니다.
도구 전략 만들기
모든 소프트웨어 애플리케이션과 마찬가지로 첫 번째 단계는 도구 전략을 계획하는 것입니다.
- 각 도구는 단일 함수로 구성되어야 합니다. 예를 들어 한 도구는 사용자를 특정 양식 유형으로 안내할 수 있고 다른 도구는 입력란을 사용자 정보와 일치시켜야 합니다. 에이전트가 어떤 도구를 사용해야 하는지 혼동할 수 있으므로 겹치는 도구를 만들지 않도록 주의하세요. 동일한 함수로 여러 작업을 처리할 수 있는지 자문해 보세요.
- 도구 등록을 관리합니다. 특정 페이지 상태에서 유용한 도구를 등록한 다음 도구를 더 이상 사용할 수 없게 되면 등록을 취소합니다.
- 복잡성 줄이기: 대부분의 애플리케이션에서 정적 등록이 기본 접근 방식이어야 합니다.
- 에이전트가 작업을 완료할 수 있도록 합니다. 엄격하거나 부정적인 안내를 작성하는 대신 에이전트가 정확한 단계 흐름을 관리할 것으로 예상하기보다는 작업을 완료하는 데 필요한 사항을 이해할 수 있다고 가정합니다.
허용되는 최대 도구 수는 없지만 각 도구는 컨텍스트 윈도우의 일부를 차지하고 완료 시간을 늘립니다. 제공하는 도구가 많을수록 도구가 겹칠수록 에이전트가 올바르게 선택하기가 더 어려워집니다. 실험을 통해 애플리케이션에 적합한 도구를 결정하세요.
이렇게 하면 목적이 겹치지 않는 개별 도구를 빌드하고 이러한 도구를 사용할 수 있는 시점을 관리할 수 있습니다.
명확한 표현과 시맨틱 코드 사용
명확하고 정확한 표현을 사용하여 도구 이름을 지정하고 도구 사용 방법을 설명하세요. 이렇게 하면 에이전트가 필요한 것을 찾고, 찾은 내용을 이해하고, 개발자가 예상하는 대로 해당 정보를 사용할 수 있습니다.
도구 이름을 작성할 때는 실행과 시작을 구분하고 발생하는 상황을 정확하게 설명하는 동사를 사용하세요. 예를 들어 create-event는 즉시 이벤트를 만드는 도구이지만 start-event-creation-process는 사용자를 이벤트 생성 양식으로 리디렉션하는 도구입니다.
명확한 설명은 도구의 기능과 사용하는 상황을 설명해야 합니다. 제한사항과 같은 부정적인 표현 대신 긍정적인 표현과 환경설정을 사용하세요.
"날씨에 이 도구를 사용하지 마세요."'
제한사항은 잘 작성된 설명에 암시되어야 합니다.
"이 도구는 특정 날짜와 시간에 예약된 캘린더 이벤트를 만들 수 있습니다."'
모델에 수행할 작업 을 알려주는 대신 이 표현은 도구가 취할 수 있는 작업을 설명합니다.
인지 컴퓨팅 최소화
복잡한 작업을 완료하는 사람의 인지 부하를 최소화해야 하는 것처럼 모델의 인지 컴퓨팅도 최소화해야 합니다.
- 원시 사용자 입력을 허용합니다. 에이전트에게 수학을 수행하거나 입력 문자열을 변환하도록 요청하지 마세요. 예를 들어 사용자가 '11:00~15:00'이라고 말하면 도구는 이를 문자열로 허용해야 합니다. 모델에 이 시간 사이의 분을 계산하도록 요청하지 마세요.
- 문자열, 숫자 또는 enum과 같은 매개변수의 특정 유형을 선언합니다.
- 특정 선택을 한 이유를 설명합니다. 선택한 내용은 자명해야 합니다. 이유를 설명하면 에이전트가 더 나은 선택을 할 수 있습니다. 예를 들어 전자상거래 쇼핑몰을 운영하는 경우 모호한 ID를 사용하는 대신 자연어로 배송 유형을 선언합니다.
shipping_id=1대신shipping="Express"를 사용합니다.
안정성 우선순위 지정
에이전트와 사람은 예상대로 작동하는 도구의 이점을 누릴 수 있습니다.
- 요금 한도에 대한 정상적인 실패를 설정합니다. 도구는 가격 비교와 같이 합리적인 반복을 허용해야 합니다. 도구에 요금 한도가 있는 경우 의미 있는 오류를 반환하거나 사용자에게 작업을 수동으로 수행하도록 안내합니다.
- 함수가 완료된 후 인터페이스 상태를 업데이트합니다. 에이전트는 인터페이스를 사용하여 다음 단계를 계획할 수 있지만 함수는 인터페이스 로드보다 완료하는 데 시간이 더 오래 걸릴 수 있습니다. 에이전트는 인터페이스가 업데이트되면 함수가 완료되었는지 확인하거나 업데이트를 다시 요청해야 합니다.
- 코드에서 엄격하게, 스키마에서 느슨하게 유효성을 검사합니다. 제약 조건 및 테스트는 바이너리 로직이 있는 함수 및 코드에 사용해야 합니다. 스키마 제약 조건이 도움이 될 수 있지만 보장되지는 않습니다. 모델이 자체 수정하고 새 유효한 매개변수로 다시 시도할 수 있도록 함수 코드에 설명 오류를 추가합니다.
평가 테스트 및 디버깅
평가 테스트를 만들고 도구를 디버깅에 사용할 수 있도록 합니다. 결정적 단위 테스트와 달리 평가는 출력이 예상치 못한 형식을 취할 수 있으므로 하드 코딩할 수 없습니다.
- 문제 정의. 입력 유형, 출력 형식, 추가 제약 조건을 포함하여 API 계약과 같이 문제를 구성할 수 있습니다.
- 기준선과 이상적인 결과를 정의합니다. 특히 텍스트 입력의 경우 어떤 유형의 결과로 원하는 출력을 얻을 수 있는지 이해하는 것이 중요합니다.
- 출력을 평가하는 방법을 결정합니다. 입력 품질, 유용성, 다음 작업을 완료하는 기능에 따라 주관적이고 정성적인 결과를 식별하고 측정할 가능성이 높습니다. 출력을 평가하는 데 사용할 수 있는 여러 가지 기술이 있습니다. 여기에는 규칙 기반 출력(문자 수 제한)에 대한 코드 기반 검사 및 LLM-as-a-judge
특정 모델의 문제를 패치하기 위해 좁은 규칙을 추가하지 마세요. 예를 들어, 존칭에 대한 선택 필드를 포함하면 모델이 잘못된 선택을 할 수 있습니다. 이 문제를 패치하기 위해 좁은 규칙을 추가하는 대신 도구를 추상화하고 조정하세요. 이 필드를 선택사항으로 설정하는 것이 가장 좋습니다. 그런 다음 에이전트에게 사용자에게 어떤 선택이 적절한지 묻도록 요청하여 사용자가 결과에 만족하도록 합니다.
참여 및 의견 공유
WebMCP는 활발히 논의 중이며 향후 변경될 수 있습니다. 이러한 API를 사용해 보고 의견이 있다면 언제든지 알려주세요.
- WebMCP 설명자를 읽고, 질문을 하고 토론에 참여하세요.
- Chrome 상태에서 Chrome 구현을 검토하세요.
- 새로운 API를 미리 살펴보고 메일링 목록에 액세스하려면 사전 체험 프로그램에 가입하세요.
- Chrome 구현에 관한 의견이 있으면 Chromium 버그를 신고하세요.