# MCP tools

Reference for all eight YouTube Translate MCP tools, including parameters, return shapes, and the budget rule for paid work.

The server exposes eight tools. Five of them return content; three manage processing.

## The budget rule

Uncached work costs money, so it takes two steps.

1. `get_processing_quote` returns `maximumCreditUnits` without spending anything.
2. The caller shows that number to the user and gets approval.
3. The content tool is called with `max_credit_units` set to at least the quoted maximum.

If a video is already cached, none of this applies: the read returns immediately at the cached price and `max_credit_units` is ignored.

Calling a content tool on an uncached video **without** `max_credit_units` is refused rather than silently charged.

## Content tools

### `get_transcript`

Returns the spoken words, with optional timestamps.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `include_timestamps` | boolean | no | Adds segment timestamps |
| `max_credit_units` | integer | for uncached | Must be at least the quoted maximum |

### `get_translation`

Renders a retained transcript into another language.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `language` | string | yes | Two-letter code, for example `es` |
| `max_credit_units` | integer | for uncached | Quoted maximum or higher |

### `get_subtitles`

Returns an SRT or VTT file. Generates the translation first if that language is missing.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `language` | string | no | Defaults to `en` |
| `format` | string | no | `srt` or `vtt`, defaults to `srt` |
| `max_credit_units` | integer | for uncached | Quoted maximum or higher |

### `get_summary`

Condenses the transcript at one of three lengths.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `language` | string | no | Defaults to `en` |
| `length` | string | no | `short`, `medium`, or `long` |
| `max_credit_units` | integer | for uncached | Quoted maximum or higher |

### `search_video`

Finds a topic or quotation inside one video and returns matching passages with timestamps.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `query` | string | yes | What to look for |
| `language` | string | no | Defaults to `en` |
| `max_credit_units` | integer | for uncached | Quoted maximum or higher |

## Processing tools

### `get_processing_quote`

Returns the cost ceiling and your current balance. Starts nothing.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `operation` | string | no | `transcribe`, `translate`, or `summarize`; defaults to `transcribe` |
| `language` | string | no | Defaults to `en` |
| `length` | string | no | Summary length, defaults to `medium` |

### `start_video`

Queues processing and returns a job ID without waiting. Use this for long videos so the conversation is not blocked.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `max_credit_units` | integer | for uncached | Quoted maximum or higher |

### `get_video_status`

Reports whether processing finished, failed, or is still running.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `video_id` | string | yes | The ID returned by `start_video` |

## Typical sequences

**Cached video, lowest cost**

```
get_transcript(url)
```

**Uncached video, with approval**

```
get_processing_quote(url, operation="transcribe")
→ user approves maximumCreditUnits
get_transcript(url, max_credit_units=<approved>)
```

**Long video, non-blocking**

```
get_processing_quote(url)
start_video(url, max_credit_units=<approved>)
get_video_status(video_id)   # repeat until completed
get_transcript(url)
```

The last call is a cached read, because `start_video` already produced the artifact.

## Related

- [Pricing and credits](/docs/pricing.md) for what each tool costs
- [Errors and retries](/docs/errors.md) for failure handling
- [Limits and retention](/docs/limits.md) for source caps
