본문으로 건너뛰기

커뮤니티

팁 운영진 번역

GitHub Docs: Copilot CLI에서 도구 검색으로 필요한 도구만 불러오기

리퀘오 운영팀

이 글은 GitHub Docs의 Copilot CLI 문서 중 도구 검색(tool search) 기능을 설명한 글을 한국어로 옮긴 것이다. MCP 서버와 외부 도구를 많이 연결해 쓰는 개발자에게, 컨텍스트 낭비와 도구 선택 정확도 저하를 줄이는 방법을 알려준다.

1. 도구 검색이 필요한 이유

MCP 서버나 외부 도구를 Copilot CLI에 연결하면 강력하지만 비용이 따른다. 도구 정의가 모델의 컨텍스트 윈도우 공간을 차지하고, 도구 목록이 길어질수록 에이전트가 알맞은 도구를 고르기 어려워진다. 필요할 때만 도구를 불러오는 방식(도구 검색)은 에이전트가 쓰지 않는 도구의 정의로 컨텍스트가 어수선해지는 것을 막는다. 에이전트는 내장 도구와 나머지 도구를 찾아보는 수단만 가지고 시작하고, 작업 수행에 필요할 때만 추가 도구를 불러온다.

도구가 늘어날 때 생기는 두 가지 문제를 해결한다.

- 컨텍스트 낭비: 도구 정의 수십 개가 에이전트가 아무 일도 하기 전에 10~20K 토큰을 잡아먹을 수 있다.
- 도구 선택 정확도 저하: 한 번에 수십 개 도구가 보이면 모델이 엉뚱한 도구를 고를 가능성이 커진다.

2. 세션 중에 일어나는 일

프롬프트를 입력할 때마다 CLI는 현재 도구 목록을 확인하고 도구 검색을 쓸지 판단한다. 대략 30개 미만이면 도구 검색으로 얻는 이득이 크지 않아 도구 검색을 건너뛰고 전부 불러온다.

도구 검색이 쓰이면 처음에는 CLI 내장 도구만 로드된다. MCP 도구와 기타 외부 도구는 보류된다. 에이전트는 그런 도구가 존재하고 대략 무엇을 하는지 알 수 있지만, 전체 정의는 아직 로드되지 않은 상태다.

에이전트가 로드되지 않은 도구가 필요한 단계에 이르면 사용 가능한 도구를 빠르게 검색해 가장 가까운 항목을 컨텍스트로 끌어온다. 이렇게 불러온 도구는 대화가 끝날 때까지 유지되므로, 각 도구는 처음 필요할 때만 검색이 일어난다.

첫 검색은 모델과 한 번 더 주고받는 비용이 들지만, 이후 매 턴마다 컨텍스트를 작게 유지해 그 비용을 여러 번 되돌려받는다.

3. 항상 로드되는 도구

일부 도구는 도구 검색을 건너뛰고 즉시 준비된다.

- Copilot CLI 내장 도구(grep, glob, bash, edit 등)
- `deferTools: "never"`로 설정한 MCP 서버의 도구
- 커스텀 에이전트가 불러온 도구

4. 도구 검색 끄기

도구 검색은 기본으로 켜져 있으며, 지원 모델을 쓰고 연결된 도구가 충분히 많으면 자동으로 작동한다. 끄고 모든 도구를 로드하는 방식으로 돌아가려면 개인 설정에서 `toolSearch: false`로 지정한다.

5. 지원 모델

- Claude(Anthropic): Mythos Preview, Fable, Haiku 4.5 이상, Sonnet 4.0 이상, Opus 4.0 이상
- GPT(OpenAI): 버전 5.4 이상

그 밖의 모델에서는 모든 도구를 미리 로드한다.

6. MCP 서버 도구를 항상 로드 상태로 유지하기

특정 MCP 서버의 도구를 항상 에이전트 앞에 두고 싶을 때가 있다. 예를 들어 늘 쓰는 서버이거나 추가 검색 단계가 이득이 없는 경우다. MCP 서버마다 이를 제어하는 `deferTools` 설정이 있다.

- `"auto"`(기본값): 다른 도구와 똑같이 동작하며, 임계값을 넘으면 보류될 수 있다.
- `"never"`: 나머지에 도구 검색이 작동하는 중에도 이 서버의 도구는 항상 에이전트 도구 목록에 포함된다.

가장 쉬운 설정 방법은 `/mcp edit` 슬래시 명령을 쓰는 것이다. MCP 서버 편집 양식에서 Defer Tools를 Never로 바꾸면 된다. `~/.copilot/mcp-config.json`에서 직접 지정할 수도 있다.

```json
{
"mcpServers": {
"my-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@example/mcp-server"],
"deferTools": "never",
"tools": ["*"]
}
}
}
```

7. 커스텀 에이전트에서 도구 보류 설정하기

커스텀 에이전트가 도구를 이름으로 나열하면 그 도구들은 항상 로드되어 에이전트가 바로 쓸 수 있다. 보통은 이게 원하는 동작이지만, 에이전트가 많은 도구를 선언하면서 한 번의 실행에서는 일부만 쓴다면 그 목록을 도구 검색에 맡겨 필요할 때 찾도록 할 수 있다.

Markdown 에이전트(`.github/agents/*.md`)라면 frontmatter에 `deferred-tool-loading: true`를 추가한다.

```markdown
---
name: my-agent
description: Works with a large catalog of tools
tools:
- some_mcp_tool
- another_mcp_tool
# ...many more
deferred-tool-loading: true
---

Agent instructions here.
```

`deferred-tool-loading` 설정에서 유의할 점은 다음과 같다.

- 도구 검색이 작동 중일 때만(지원 모델에서 도구가 임계값을 넘을 때) 효과가 있다.
- 도구를 이름으로 지정한 에이전트에만 의미가 있다. `*` 와일드카드를 쓰는 에이전트는 이미 도구 검색을 사용한다.

8. 도구 검색에 맞게 도구 최적화하기

도구 검색은 에이전트가 하려는 일을 각 도구의 이름, 설명, 매개변수 이름과 설명에 대조한다. 명확하고 구체적인 표현이 도구가 알맞은 요청에 나타나게 한다.

- 도구 이름은 하는 일을 기준으로 지어 찾기 쉽게 한다.
- 설명은 모호한 표현 대신 사람들이 실제로 검색할 법한 단어로 쓴다.

여러분은 Copilot CLI에서 도구 검색을 써 보면서 컨텍스트 사용량이나 도구 선택이 어떻게 달라졌는지 댓글로 경험을 나눠 주세요.

---
출처: GitHub Docs 「도구 검색으로 필요할 때 도구 불러오기」 (GitHub)
https://docs.github.com/en/copilot/concepts/agent-capabilities/agent-powered-workflows-and-operations/tool-search
라이선스: CC BY 4.0 https://creativecommons.org/licenses/by/4.0/deed.ko
변경 사항: 리퀘오 운영팀이 2026-11-10에 한국어로 번역하고 일부 축약·재구성했습니다. 원문 작성자가 이 번역을 보증하지 않습니다.

로그인하면 누를 수 있습니다. 로그인하면 저장하고 새 답글 알림을 받을 수 있습니다.

답글 0

아직 답글이 없습니다.