# 도구가 많아질 때

> **이 장에서 배우는 것**
> 도구가 늘어날 때 생기는 두 가지 문제와, 실무에서 쓰는 해결책.

## 금방 수십 개가 됩니다

MCP 서버 몇 개만 붙여도 도구는 빠르게 늘어납니다.

```
Slack 서버      → 12개 (메시지 보내기, 채널 목록, 검색, ...)
GitHub 서버     → 25개 (이슈, PR, 커밋, 파일, ...)
Google Drive    → 15개
사내 ERP        → 30개
──────────────────────
합계              82개
```

서버 4개인데 도구는 82개입니다. 그리고 여기서 두 가지 문제가 생깁니다.

## 문제 1 — 자리를 차지합니다

**도구 정의는 전부 [컨텍스트](/guide/ai-context-window)에 들어갑니다.** 이름,
설명, 인자 스펙까지 전부입니다.

```
도구 하나당 대략 100~200 토큰
82개 × 150 = 약 12,000 토큰
```

**아직 아무 일도 안 했는데 컨텍스트의 상당 부분이 찼습니다.** 그리고 이건 매
요청마다 반복됩니다 — 대화할 때마다 82개 도구 설명을 다시 보냅니다.

| 결과 | |
|---|---|
| 비용 | 매 요청마다 그만큼 더 냄 |
| 여유 공간 | 정작 일할 자리가 줄어듦 |
| [밀려남](/guide/ai-context-overflow) | 긴 작업에서 더 빨리 참 |

## 문제 2 — 잘못 고릅니다 (더 중요)

이쪽이 실무에서 더 아픕니다.

도구가 82개면 그중 비슷한 것들이 생깁니다.

```
검색   (Slack)
검색   (GitHub)
문서검색 (Drive)
자료조회 (ERP)
통합검색 (사내포털)
```

"작년 계약서 찾아줘"라고 하면 **어느 것을 불러야 합니까?** 모델도 헷갈립니다.

> **사람도 공구가 200개 놓인 작업대에서 맞는 것을 더 자주 틀리게 집습니다.**
> 후보를 줄이는 것은 비용 절감인 동시에 **선택 정확도**를 올리는 일입니다.

## 해결책 1 — 필요한 것만 켜기

가장 단순하고 효과적입니다. **안 쓰는 도구는 끕니다.**

```
✗ 붙일 수 있는 건 다 붙여두고 나중에 정리
✓ 이 워크스페이스가 실제로 쓰는 것만 켜기
```

[Connect](/guide/cn-agents-intro)에서 워크스페이스별로 도구를 켜고 끌 수 있는
이유가 이것입니다. 영업팀 워크스페이스에 개발 도구가 켜져 있을 이유가 없습니다.

## 해결책 2 — 요청에 맞는 것만 골라 넘기기

전부 넘기지 않고 **이번 요청에 필요해 보이는 것만** 추립니다.

```mermaid
graph TD
  A["도구 140개"] --> B["스레드 첫 요청:<br/>'작년 계약서 찾아줘'"]
  B --> C["요청과 가까운 도구 추리기"]
  C --> D["가까운 것부터 상위 N개만<br/>모델에게"]
  D --> E["선택이 쉬워짐 · 컨텍스트 절약"]
  E --> F["이 대화 내내 같은 묶음을 씀"]
```

Connect는 도구 설명을 벡터로 만들어두고 요청과 가까운 것부터 추립니다. 상위 N개
안에 들어도 **너무 먼 것은 제외**합니다(`TOOL_SELECTION_MIN_SIMILARITY`, 기본 0.3).

> **다만 이 장치는 항상 도는 게 아닙니다.** 도구 수가 임계값(기본 100개)을 넘을
> 때만 작동합니다. 그 아래에서는 **켜져 있는 도구가 전부 그대로 전달됩니다** —
> 그래서 안 쓰는 도구를 꺼두는 게 더 중요합니다. 임계값과 추릴 개수는
> `TOOL_SELECTION_THRESHOLD` · `TOOL_SELECTION_TOP_K` 로 조정합니다.

### 한 번 고르면 그 대화 내내 유지됩니다

메시지마다 다시 고르지 않습니다. **스레드의 첫 턴에 고른 묶음을 그대로**
씁니다.

도구 정의는 프롬프트 맨 앞에 실리기 때문에, 메시지마다 도구가 바뀌면 그 뒤의
지시문과 대화 이력까지 캐시가 통째로 무효화됩니다. 고정해두는 편이 훨씬
쌉니다.

실무에서 이게 뜻하는 것은 하나입니다.

```
✗ 대화 중간에 "아까는 없던 도구"가 갑자기 생기지 않음
✓ 다른 도구가 필요하면 → 새 스레드
```

워크스페이스의 도구 구성을 바꾸면 그때는 다시 고릅니다.

> **지목한 것은 무조건 들어갑니다.** 대화에서 `@이름` 으로 부른 에이전트의
> 도구는 유사도와 상관없이 항상 포함됩니다. 필요한 도구가 빠졌다 싶으면 이름을
> 직접 부르는 것이 가장 확실합니다.

## 해결책 3 — 도구를 잘 나누기

설계 단계의 이야기입니다.

| 나쁜 설계 | 좋은 설계 |
|---|---|
| `데이터조회(종류, 조건)` 하나로 다 처리 | `재고조회` / `주문조회` / `고객조회` 로 분리 |
| 이름이 비슷한 것 여럿 | 이름만 봐도 구분되게 |
| 설명이 한 줄 | 언제 쓰고 뭘 주의할지까지 |

**하나로 뭉친 만능 도구는 편해 보이지만 모델이 인자를 자주 틀립니다.** 나누는
쪽이 낫습니다.

## 얼마나가 적당한가

정해진 수는 없지만 실무 감각은 이렇습니다.

| 도구 수 | 상태 |
|---|---|
| ~10개 | 문제 없음 |
| 10~30개 | 이름과 설명이 좋으면 괜찮음 |
| 30~50개 | 골라 넘기는 장치가 있으면 좋음 |
| 50개 이상 | **장치 없이는 정확도 저하가 보임** |

> 위는 업계 일반의 감각입니다. **Connect의 자동 추리기는 100개를 넘어야 켜지므로**,
> 30~100개 구간은 [워크스페이스 도구 설정](/guide/cn-tool-settings)에서 직접 꺼서
> 줄여야 합니다.

## 자주 하는 오해

### "모델이 좋아지면 해결되지 않나?"

일부는 그렇습니다. 그런데 **컨텍스트를 차지하는 문제는 그대로**입니다. 도구 정의가
12,000 토큰이면 모델이 아무리 좋아도 그 자리는 비지 않습니다.

### "골라 넘기면 필요한 도구를 놓치지 않나?"

가능합니다. 그래서 추리는 기준을 너무 좁게 잡으면 안 됩니다. 실무에서는
**넉넉하게 추립니다.** Connect의 기본값도 상위 100개로 넓게 잡혀 있습니다 — 너무
좁게 자르면 필요한 도구가 빠지기 때문입니다.

---

## 확인

**1. 도구 82개를 붙이면 아직 아무 일도 안 했는데 왜 컨텍스트가 찹니까?**

<details>
<summary>답</summary>

**도구 정의(이름·설명·인자)가 전부 컨텍스트에 들어가기 때문**입니다. 도구 하나당
100~200 토큰이면 82개는 1만 토큰이 넘고, 이게 매 요청마다 반복됩니다.
</details>

**2. 도구가 많을 때 비용보다 더 아픈 문제는 무엇입니까?**

<details>
<summary>답</summary>

**잘못 고르는 것**입니다. 비슷한 도구가 여럿이면 모델이 어느 것을 불러야 할지
헷갈립니다. 후보를 줄이는 것은 비용 절감인 동시에 선택 정확도를 올리는 일입니다.
</details>

**3. 만능 도구 하나 대신 여러 개로 나누는 게 나은 이유는?**

<details>
<summary>답</summary>

**하나로 뭉치면 모델이 인자를 자주 틀리기 때문**입니다. `데이터조회(종류, 조건)`
보다 `재고조회` / `주문조회`로 나누면 이름만 봐도 구분되어 선택이 정확해집니다.
</details>

---

다음은 도구가 아니라 **읽은 자료**가 위험해지는 경우입니다 →
[읽은 것이 명령이 될 때](/guide/mcp-prompt-injection)