브라우저가 할 수 있는 일이 늘수록 에이전트에게 설명할 도구도 늘었다. 모든 설명을 매번 넣으면 작은 읽기 작업에서도 긴 명령 목록을 다시 보게 된다. 나는 도구를 실행하는 입구와 필요한 도구의 계약을 발견하는 입구를 나눴다.

전체 목록을 아는 것과 지금 쓸 도구를 아는 것

현재 작업의 제목을 읽으려는 단계에서 업로드·예약·플러그인 수정의 모든 매개변수를 알 필요는 없다. 우선 reading 묶음의 계약을 읽고 관찰과 검색, 추출에 필요한 입력을 확인한다. 다음에 입력이 필요해지면 그때 input 묶음을 읽는 식이다.

이 구분은 모델이 나머지 능력을 영원히 잃는다는 뜻이 아니다. 도구 발견 함수를 유지하면서 당장 처리할 문제의 설명만 가져온다. 전체 설명을 줄이는 목적과 실제 실행 권한을 줄이는 목적을 혼동하지 않았다. 어떤 작업을 허용할지는 사용자 요청과 호스트의 검사로 따로 정한다.

설명도 실제 계약에서 만든다

externalSchemas는 ToolCall의 실제 옵션에서 해당 묶음에 속하는 도구를 고르고 JSON Schema로 변환한다. 실행기와 무관한 별도 안내문에 필드 이름을 손으로 두 번 적는 방식보다 변경을 따라가기 쉽다. 읽기 전용 설명을 얻었다고 실행이 시작되지는 않는다.

상위 MCP에는 northstar_tools가 있고 family와 필요한 경우 name을 받는다. name을 지정하면 더 작은 단위로 필요한 계약을 요청할 수 있다. 이름을 모르면 먼저 묶음을 보고 고른다. 발견 단계가 다음 조작의 정확한 입력을 준비하는 역할을 맡고 조작 자체를 대신하지 않는다.

묶음 이름을 권한의 증거로 쓰지 않는다

reading에는 관찰뿐 아니라 기다리기와 스크롤, 탭 선택에 쓰이는 계약도 있다. 묶음의 이름만 보고 모든 항목이 아무 상태도 바꾸지 않는다고 설명하면 부정확하다. 그룹은 발견을 위한 분류이고 각 도구의 실제 행동과 조건은 개별 계약을 읽어야 한다.

all도 모든 내부 기능을 무제한 공개한다는 뜻은 아니다. 내부 에이전트 수리 같은 차단 도구는 전체 묶음에서도 제외한다. 같은 ToolCall에 역사적으로 남은 항목이 있다고 현재 외부 MCP가 호출할 수 있다고 연결하지 않는다. 분류표와 실제 허용 경계를 나눠 둔 이유다.

발견한 뒤에도 입력은 다시 검사한다

스키마를 읽은 에이전트가 잘못된 입력을 만들 가능성은 남는다. 실제 호출은 taskId와 call을 보내고 서버의 ExternalRequest와 ToolCall 검사를 거친다. 설명을 한 번 읽었다는 기록을 실행 시 검증을 생략하는 표로 쓰지 않는다.

계약이 바뀐 뒤 예전 입력을 보낸 경우도 마찬가지다. 새 매개변수를 추측해서 붙이거나 모르는 필드를 무시하며 실행하지 않는다. 호출자는 현재 계약을 읽어 수정하고, 호스트는 현재 문맥과 실제 대상을 확인한다. 발견과 검증을 따로 둬야 잘못 읽은 설명이 바로 조작으로 이어지지 않는다.

시험은 무엇이 들어오고 빠지는지를 본다

관련 통합 시험은 reading에 observe가 포함되고 fill은 포함되지 않는지 확인한다. 내부 수리 도구가 all에서도 빠지는지, 임의 evaluate와 추가 자바스크립트 필드가 거절되는지도 검사한다. 이 글에서는 그 실제 시험 코드와 현재 필터 함수를 읽어 범위를 대조했다.

새 모델을 불러 도구 선택의 정확도나 토큰 절감률을 측정한 것은 아니다. 설명을 작게 나눴다는 구현만으로 대화 전체가 일정 비율 빨라진다고 주장하지 않는다. 모델이 여러 묶음을 불필요하게 반복 조회하면 오히려 비용이 늘 수 있으므로 실제 업무 기록에서 발견 순서도 살펴야 한다.

기능을 찾는 비용도 제품 설계다

업무 프로그램에서 기능이 많다는 것과 필요한 기능을 쉽게 찾는다는 것은 다르다. 나는 에이전트에게도 같은 문제가 있다고 봤다. 처음에는 작은 입구를 주고 실제 작업이 요구하는 상세를 단계별로 읽게 하면 설명과 실행의 관계가 더 분명해진다.

다른 시스템에 적용할 때도 그룹 수를 그대로 복사할 필요는 없다. 실제 업무에서 함께 쓰는 도구와 변경 범위를 기준으로 나누고, 같은 실행 계약에서 설명을 생성한다. 발견 호출의 성공, 실제 행동의 성공, 업무 완료를 각각 기록해야 이 구조가 어디에 도움을 줬는지 알 수 있다.