# 도구 레퍼런스

> 모모콜 MCP 서버가 제공하는 도구 10개의 입력, 출력, 필요한 허용 항목, 크레딧을 정리했습니다. 모든 도구는 읽기 전용이며 본인 데이터만 돌려줍니다.

- 원문 주소: https://momocall.kr/docs/ai/tools
- 쓸 수 있는 요금제: 모든 요금제
- 마지막 확인: 2026-11-16
- 이런 분께 맞아요:
  - 개발자: 연동 스크립트를 짜기 전에 필드 이름과 페이지 단위를 확인
  - AI 에이전트: 어떤 도구를 어떤 인자로 부를지 정할 때 참고

## 한눈에 보기

| 도구 | 하는 일 | 필요한 허용 항목 | 크레딧 |
|---|---|---|---|
| `get_context` | 허용 항목, 남은 AI 검색 횟수, 최근 동기화 시각, 한도 | `context:read` | 0 |
| `list_calls` | 기간·방향·고객별 통화 목록 | `calls:read` | 0 |
| `get_calls` | 통화 상세·요약·연결된 할 일·녹음 여부 | `calls:read` (요약은 `summaries:read`) | 0 |
| `get_transcript` | 발화 단위 전사 | `calls:read` + `transcripts:read` | 0 |
| `list_agenda` | 통화에서 나온 일정·할 일 | `agenda:read` | 0 |
| `find_customers` | 정확한 이름으로 고객 후보 찾기 | `calls:read` | 0 |
| `get_call_metrics` | 통화 수·연결 수·통화 시간 집계 | `calls:read` | 0 |
| `get_changes` | 추가·수정·삭제 내역 (동기화 진단용) | `calls:read` | 0 |
| `get_integration_guide` | 연동 가이드 문서 | — | 0 |
| `search_conversations` | 모모콜 AI 검색 | `search:execute` + `summaries:read` | **1** |

공통 규칙

- 시각 입력은 **시간대가 들어간 RFC3339** 형식입니다. 예: `2026-11-16T00:00:00+09:00`. 출력 시각은 UTC입니다.
- `end`는 그 시각을 포함하지 않습니다.
- 한 번에 조회하는 기간은 최대 366일입니다.
- 정의되지 않은 인자를 보내면 `INVALID_ARGUMENT`로 거부됩니다.
- 통화 상대에게서 나온 텍스트는 `{"untrusted": true, "text": "..."}` 형태로 옵니다.

## get_context

연결 상태를 확인합니다. 인자가 없습니다.

| 출력 필드 | 뜻 |
|---|---|
| `granted_scopes` | 사용자가 허용한 항목 목록 |
| `ai_search` | `tier`, `period`(`lifetime`·`month`), `limit`, `used`, `remaining`, `resets_at`. 검색을 허용하지 않았으면 `null` |
| `latest_call_started_at` | 서버에 올라온 가장 최근 통화 시각 |
| `limits` | `list_max` 100, `get_calls_max_ids` 20, `transcript_segments_max` 200, `range_max_days` 366, `search_query_max_chars` 500 |

## list_calls

기간 안의 통화를 최신순으로 빠짐없이 나열합니다.

| 인자 | 기본값 | 설명 |
|---|---|---|
| `start` | `end`의 7일 전 | 시작 시각 |
| `end` | 지금 | 끝 시각 (미포함) |
| `direction` | 전체 | `INBOUND` · `OUTBOUND` · `MISSED` · `UNKNOWN` |
| `limit` | 50 | 1~100 |
| `cursor` | — | 이전 응답의 `next_cursor` |
| `customer_key` | — | `find_customers`가 준 값 |

출력: `calls[]`(`call_id`, `started_at`, `ended_at`, `duration_seconds`, `direction`, `contact_name`), `next_cursor`, `completeness`(`complete`·`partial`).

> [!AGENT]
> `completeness`가 `partial`이면 아직 남은 통화가 있습니다. 같은 인자에 `cursor`만 바꿔 계속 부르세요. 조건을 바꾸고 이전 커서를 쓰면 `CURSOR_MISMATCH` 오류가 납니다.

## get_calls

통화 상세 정보를 한 번에 최대 20건까지 가져옵니다.

| 인자 | 설명 |
|---|---|
| `call_ids` | 1~20개의 `call_id` |

출력: `items[]`마다 `status`(`ok`·`processing`·`entitlement_required`·`not_available`), `call`, `summary`, `action_items[]`, `recording.available`.

- 없거나 볼 수 없는 ID는 모두 `not_available`로 동일하게 응답합니다.
- 녹음 파일은 모모콜 앱에서만 재생할 수 있습니다. AI가 오디오를 직접 듣지 않습니다.

## get_transcript

통화 1건을 발화 단위로 나누어 돌려줍니다. 전사 항목을 허용해야 합니다.

| 인자 | 기본값 | 설명 |
|---|---|---|
| `call_id` | — | 통화 ID |
| `offset` | 0 | 시작 발화 번호 |
| `limit` | 50 | 1~200 |

출력: `segments[]`(`index`, `speaker`, `start_ms`, `end_ms`, `text`), `next_offset`(남은 발화가 있을 때).

## list_agenda

통화에서 나온 일정과 할 일을 최신순으로 나열합니다.

| 인자 | 기본값 | 설명 |
|---|---|---|
| `status` | 전체 | `open`(진행 중) · `done`(완료) |
| `limit` | 50 | 1~100 |
| `cursor` | — | 이전 응답의 `next_cursor` |

출력 항목: `id`, `call_id`, `kind`, `title`, `description`, `start_time`, `due_at`, `end_time`, `all_day`, `status`. `due_at`이 `null`이면 기한이 없는 할 일입니다.

## find_customers

이름이 **정확히 일치하는** 통화 상대를 번호별 후보로 돌려줍니다. 동명이인은 합치지 않습니다.

| 인자 | 기본값 | 설명 |
|---|---|---|
| `name` | — | 고객 이름 (1~100자) |
| `limit` | 10 | 1~20 |

출력: `candidates[]`(`customer_key`, `contact_name`, `phone_hint`(끝 4자리), `call_count`, `first_call_at`, `last_call_at`), `requires_user_choice`.

> [!LIMIT]
> `customer_key`는 24시간 동안 유효합니다.

## get_call_metrics

서버가 통화 수를 정확히 집계합니다. 일별 묶음은 한국 시간 기준입니다.

| 인자 | 기본값 | 설명 |
|---|---|---|
| `start` | `end`의 30일 전 | 시작 시각 |
| `end` | 지금 | 끝 시각 (미포함) |
| `group_by` | `none` | `none` · `day` · `direction` |

출력 `rows[]`: `bucket`, `total`, `connected`(부재중이 아니고 통화 시간이 0보다 큰 통화), `outbound`, `inbound`, `missed`, `duration_unknown`, `duration_seconds`.

## get_changes

통화의 추가·수정·삭제 내역을 오래된 순으로 한 페이지씩 돌려줍니다. 상세 내용 없이 ID와 시각만 전달합니다.

| 인자 | 기본값 | 설명 |
|---|---|---|
| `sync_cursor` | 처음부터 | 이전 응답의 `sync_cursor` |
| `limit` | 20 | 1~50 |

출력: `changes[]`(`call_id`, `updated_at`, `deleted`, `started_at`), `sync_cursor`, `has_more`.

> [!LIMIT]
> `sync_cursor`는 30일 동안 유효하며, 결과가 비어 있어도 항상 새 값이 전달됩니다. 만료되면 `list_calls`로 처음부터 다시 맞춰야 합니다.

## get_integration_guide

| 인자 | 값 |
|---|---|
| `topic` | `overview` · `auth` · `data` · `tools` · `errors` · `crm-mapping` · `sync` · `limits` |

같은 내용을 MCP 리소스 `momocall://guides/{topic}`으로도 제공합니다.

## search_conversations

모모콜 앱의 AI 검색과 같은 엔진으로 통화를 찾습니다. **호출할 때마다 크레딧 1개를 씁니다.**

| 인자 | 설명 |
|---|---|
| `query` | 찾을 내용을 자연어로 입력 (1~500자) |

출력: `found`, `answer`(요약 기반 답변), `hits[]`(`call_id`, `started_at`, `contact_name`, `title`, `summary[]`, `cited`), `credits_charged`, `usage`, `completeness`(항상 `not_exhaustive`).

> [!LIMIT]
> - 월 크레딧: 무료 누적 30회 · 베이직 100회 · 프로 300회 · 프리미엄 1,000회. 앱과 함께 씁니다.
> - 결제 갱신이나 연간 구독 월 리필 때 새로 채워집니다. 무료 30회는 다시 채워지지 않습니다.
> - 검색에 실패하거나 검색 범위를 벗어난 질문에는 크레딧을 돌려드립니다. 결과가 0건이어도 정상적으로 검색되었다면 크레딧을 씁니다.
