에이전트가 도구를 다룰 때 이름이 비슷한 매개변수를 추측해 넣는 경우가 있다. 프로그램이 그것을 무시하고 나머지만 실행하면 사용자는 요청 전체가 반영됐다고 생각할 수 있다. 나는 실행 입구에서 모르는 필드를 거절하는 쪽을 택했다.
무시된 조건이 잘못된 성공을 만든다
예를 들어 예약 날짜를 잘못된 키에 넣었는데 프로그램이 그 키를 무시하면 기본 동작이 실행될 수 있다. 오류가 났다는 표시가 없으면 호출자는 일정까지 반영됐다고 보고한다. 사용자가 중요하게 생각한 조건이 사라진 채 나머지가 성공하는 상황이다.
strictObject는 선언한 키 밖의 값을 거절한다. 이 검사가 자연어의 모든 오해를 잡아 주지는 않지만 적어도 구현이 모르는 조건을 받은 채 조용히 진행하지 않는다. 나는 더 관대한 입력이 항상 더 친절한 API라고 보지 않았다. 잘못된 부분을 드러내고 현재 계약을 다시 읽게 하는 편이 명확했다.
바깥 봉투와 안쪽 동작을 나눠 검사한다
MCP 중계기는 도구 이름과 최상위 인자, 필수 키를 확인한다. 브라우저 파이프는 다시 ExternalRequest와 내부 ToolCall을 파싱한다. 바깥 입구의 JSON Schema가 모든 세부 조건을 실행 시 완전 검증한다고 설명하지 않는다. 실제 강한 검사는 호스트의 현재 계약에서 이어진다.
call 안에 임의 javascript를 붙이거나 존재하지 않는 browser.evaluate를 보내는 경우가 관련 시험에서 거절된다. 상위 객체가 유효해도 내부 도구가 유효하다는 뜻은 아니다. 두 단계의 역할을 나눠야 중계기에서 일부 필드만 검사한 사실을 전체 유효성 검사로 과장하지 않게 된다.
형식이 맞아도 행동별 조건은 더 필요하다
같은 plugin 요청에도 list·inspect·run·status 같은 action이 있다. 어떤 값은 선택적 스키마에 있지만 실제 action에서는 필요할 수 있다. UUID 모양이 맞는 taskId라도 현재 실행과 다르면 거절한다. 형식 검사와 현재 상태 검사는 서로를 대신하지 않는다.
context의 profileId·workspaceId·tabId는 모두 존재하는 문자열이어야 하지만 그것만으로 소유권이 증명되지는 않는다. 실제 호스트의 현재 값과 맞는지 확인한다. 공개 입력 계약에는 무엇을 받아들이는지 적고 실행 계층에는 지금 받아도 되는지 검사하는 책임을 남겼다.
크기 제한도 업무의 일부다
목표 문장과 매개변수 이름, 입력 본문에는 길이 제한이 있다. 파일 생성 입구도 이름과 명시한 바이트만 받고 임의 로컬 경로를 받지 않는다. 긴 문자열을 무조건 잘라 실행하면 중요한 본문이나 조건을 잃을 수 있으므로 계약 위반을 오류로 돌려줘야 한다.
이 제한을 파일 시스템 전체의 접근 통제로 오해해서는 안 된다. 기존 Python 실행은 사용자의 로컬 권한을 가진다. 입력 길이 검사는 해당 API의 메시지 경계다. 나는 한 엔드포인트의 좁은 제한과 주변 실행 환경의 권한을 따로 설명해 연결하는 사람이 잘못된 보장을 기대하지 않게 했다.
계약을 바꿀 때는 호출자를 함께 본다
새 필드를 넣는 일은 설명서 한 줄 추가로 끝나지 않는다. 중계기의 발견 스키마와 호스트의 파서, 실제 action 처리와 오류 문구를 함께 맞춰야 한다. 한쪽만 바꾸면 에이전트가 발견한 입력이 다른 쪽에서 거절되거나 뜻이 다르게 처리될 수 있다.
이 글은 현재 스키마와 통합 시험의 실제 거절 사례를 읽어 정리했다. 모든 가능한 입력 조합을 새로 퍼징한 보고서는 아니다. 알 수 없는 필드와 임의 실행 도구의 거절이 구현돼 있다는 근거와 모든 의미 오류를 막는다는 주장은 구별한다. 날짜의 형식과 실제 달력 유효성 같은 세부 조건도 개별 계약을 봐야 한다.
실패를 설명할 수 있어야 입력도 고친다
에이전트 친화적인 도구는 아무 문자열이나 받아 주는 도구라고 생각하지 않는다. 무엇이 부족하고 어떤 계약을 다시 봐야 하는지 알 수 있어야 다음 입력을 정확히 만들 수 있다. 알 수 없는 필드 하나를 명확히 거절하는 일이 잘못된 기본 동작을 실행한 뒤 수습하는 일보다 작다.
다른 업무 API에도 이 원칙을 적용할 수 있다. 필요한 필드와 범위, 실제 상태 조건을 정하고 발견한 계약과 실행 검사가 같은 뜻을 갖게 한다. 형식 통과를 업무 완료라고 보고하지 않으며 결과 검증을 다음 단계로 남긴다. 나는 입력을 명확히 하는 일이 에이전트의 판단을 돕는 인터페이스라고 봤다.