> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poix.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Reference

> All 11 tools exposed by the Poix MCP server

The Poix MCP server exposes 11 tools over `https://mcp.poix.io`. Every tool is a thin wrapper around the corresponding Poix REST API endpoint, so inputs, outputs, and billing match the [API Reference](/api-reference/authentication) exactly — nothing added, nothing hidden.

<Note>
  Every tool call is billed against your Poix balance the same way a REST API request is. Cost is denominated in **quota units** for endpoints that mirror the YouTube Data API (see [Pricing](/pricing) for the underlying \$/unit rate), or a flat **credit** for endpoints backed by Poix's media/caption providers.
</Note>

## Search & Discovery

### `search_videos`

Search YouTube for videos, channels, and playlists by keyword, with the full set of YouTube search filters (date range, duration, category, region, language, and more).

| Input                                                                                   | Type   | Required | Notes                                                                       |
| --------------------------------------------------------------------------------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `q`                                                                                     | string | No       | Search query. Supports boolean `OR` (`\|`) and `NOT` (`-`)                  |
| `type`                                                                                  | string | No       | Comma-separated `video,channel,playlist` (default: all three)               |
| `maxResults`                                                                            | number | No       | 0–50 (default 50)                                                           |
| `order`                                                                                 | enum   | No       | `relevance` (default), `date`, `rating`, `title`, `viewCount`, `videoCount` |
| `regionCode` / `relevanceLanguage`                                                      | string | No       | ISO 3166-1 alpha-2 / ISO 639-1                                              |
| `videoDuration` / `videoDefinition` / `videoCategoryId` / `channelId` / `pageToken` / … | —      | No       | Full set mirrors [`GET /search`](/api-reference/search/get-search-results)  |

**Cost:** 100 quota units per call (\~\$0.00203) — the most expensive single tool, matching the YouTube Data API's own `search.list` cost.

### `search_autocomplete`

Get YouTube's search-suggestion completions for a partial query — useful for query refinement before a full `search_videos` call.

| Input        | Type   | Required | Notes                           |
| ------------ | ------ | -------- | ------------------------------- |
| `q`          | string | Yes      | Partial search query            |
| `regionCode` | string | No       | ISO 3166-1 alpha-2 country code |

**Cost:** 1 quota unit per call (\~\$0.00013).

### `get_related_videos`

Get videos related to a given video, ranked by the provider. The source video is never returned, and duplicates across pages are removed. Mirrors [`GET /relatedVideos`](/api-reference/videos/get-related-videos).

| Input        | Type   | Required | Notes                                                                        |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------- |
| `videoId`    | string | Yes      | 11-character source video ID                                                 |
| `pages`      | number | No       | Provider pages to fetch, 1-10 (default 1). Each page returns up to 20 videos |
| `lang`       | string | No       | Preferred language code for results                                          |
| `regionCode` | string | No       | ISO 3166-1 alpha-2 country code                                              |

**Cost:** No YouTube Data API quota units — this tool is served by Poix's related-videos provider. Billed at \~$0.00053 for one page, rising by ~$0.0005 per additional page to \~\$0.00503 for ten. Only pages actually fetched are charged; the `pagesFetched` field in the response reports how many that was.

## Details

### `get_video_details`

Get full metadata for up to 50 videos by ID: title, description, stats, tags, category, duration, and more.

| Input     | Type   | Required | Notes                                                   |
| --------- | ------ | -------- | ------------------------------------------------------- |
| `ids`     | string | Yes      | Comma-separated list of 11-character video IDs (max 50) |
| `hl`      | string | No       | Language for localized fields                           |
| `fields`  | string | No       | Comma-separated subset of response fields to return     |
| `include` | string | No       | Additional derived fields, e.g. `isShort`               |

**Cost:** 1 quota unit per call (\~\$0.00013), regardless of how many IDs are batched in.

### `get_popular_videos`

Get the current popular/trending videos list, filterable by region and category.

| Input                      | Type   | Required | Notes                           |
| -------------------------- | ------ | -------- | ------------------------------- |
| `regionCode`               | string | No       | ISO 3166-1 alpha-2 country code |
| `videoCategoryId`          | string | No       | YouTube video category ID       |
| `hl`                       | string | No       | Language for localized fields   |
| `maxResults` / `pageToken` | —      | No       | Pagination                      |

**Cost:** 1 quota unit per call (\~\$0.00013).

### `get_channel_details`

Get full metadata for one or more channels, looked up by ID, handle, or legacy username.

| Input           | Type   | Required                                   | Notes                                                     |
| --------------- | ------ | ------------------------------------------ | --------------------------------------------------------- |
| `ids`           | string | One of `ids` / `forHandle` / `forUsername` | Comma-separated list of 24-character channel IDs (max 50) |
| `forHandle`     | string | —                                          | Channel handle (e.g. `@poix`)                             |
| `forUsername`   | string | —                                          | Legacy channel username                                   |
| `hl` / `fields` | —      | No                                         | Localization / field filtering                            |

**Cost:** 1 quota unit per call (\~\$0.00013).

## Playlists & Comments

### `get_playlist_items`

Get the items in a playlist, or a channel's uploads, or look up specific playlist-item IDs.

| Input        | Type   | Required                                          | Notes                                        |
| ------------ | ------ | ------------------------------------------------- | -------------------------------------------- |
| `playlistId` | string | Exactly one of `playlistId` / `channelId` / `ids` | Playlist to list items from                  |
| `channelId`  | string | —                                                 | Returns the channel's uploads playlist items |
| `ids`        | string | —                                                 | Comma-separated specific playlist-item IDs   |
| `pageToken`  | string | No                                                | Pagination                                   |

**Cost:** 1 quota unit per call (\~\$0.00013).

### `get_comments`

Get top-level comment threads for a video or channel, or look up specific comment IDs, with sorting and text search.

| Input                      | Type   | Required                                              | Notes                                |
| -------------------------- | ------ | ----------------------------------------------------- | ------------------------------------ |
| `videoId`                  | string | Exactly one of `videoId` / `channelId` / `commentIds` | 11-character video ID                |
| `channelId`                | string | —                                                     | 24-character channel ID              |
| `commentIds`               | string | —                                                     | Comma-separated comment IDs (max 50) |
| `order`                    | enum   | No                                                    | `time` or `relevance`                |
| `searchTerm`               | string | No                                                    | Filters threads containing this term |
| `format`                   | enum   | No                                                    | `html` (default) or `plainText`      |
| `maxResults` / `pageToken` | —      | No                                                    | 1–100 (default 100) / pagination     |

**Cost:** 1 quota unit per call (\~\$0.00013).

### `get_comment_replies`

Get replies to a specific top-level comment.

| Input             | Type   | Required | Notes                               |
| ----------------- | ------ | -------- | ----------------------------------- |
| `parentCommentId` | string | Yes      | The comment ID to fetch replies for |
| `format`          | enum   | No       | `html` (default) or `plainText`     |
| `pageToken`       | string | No       | Pagination                          |

**Cost:** 1 quota unit per call (\~\$0.00013).

## Media & Captions

### `get_video_files`

Get direct, time-limited URLs for a video's underlying video/audio media formats and their metadata (resolution, bitrate, size, container).

| Input        | Type   | Required | Notes                                                          |
| ------------ | ------ | -------- | -------------------------------------------------------------- |
| `videoId`    | string | Yes      | 11-character video ID                                          |
| `regionCode` | string | No       | ISO 3166-1 alpha-2 country code, for region-restricted content |

**Cost:** flat credit per call (\~\$0.00053), matching the [`GET /files/video/{videoId}`](/api-reference/files/get-video-files-list) rate.

### `get_video_captions`

Get a video's captions/transcript as structured JSON (with per-line timing and speech rate) or as plain text.

| Input     | Type   | Required | Notes                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `videoId` | string | Yes      | 11-character video ID                                                                  |
| `lang`    | string | No       | ISO 639-1 language code; defaults to the video's native caption language               |
| `format`  | enum   | No       | `json` (default), `text`, `csv`, `srt`, `vtt`, or `ttml`                               |
| `mode`    | enum   | No       | `default`, `fallback-whisper`, `force-whisper`, `fallback-auto-translated` — see below |

The `mode` parameter controls what happens when native captions aren't available in the requested language: `default` errors out, `fallback-auto-translated` uses YouTube's auto-translated captions, `fallback-whisper` transcribes with Whisper only if no captions exist at all, and `force-whisper` always transcribes with Whisper.

**Cost:** flat credit per call (\~\$0.00053) for native/auto-translated captions, matching [`GET /captions/{videoId}`](/api-reference/captions/get-video-captions). Whisper-fallback modes (`fallback-whisper`, `force-whisper`) cost more, billed by audio duration/GPU time — avoid `force-whisper` unless you specifically need it.