# MCP tools

> Every tool of the Moknah MCP server by group, with what it does, whether it spends credits, and which plan it needs.

The exact arguments of each tool are in the schema the server sends to the client. This page says what each tool is for.

Legend: **Free** spends no credits. **Billable** spends credits, and only after `confirm_spend` is true. **Every plan** works without an Audio Studio plan; all other tools need a plan that includes Audio Studio.

## Documentation

All free, read-only, every plan, and available to every token whatever its scopes.

| Tool | Purpose |
| --- | --- |
| `search_docs` | Search this documentation in English or Arabic. Returns matching sections with a snippet, a relevance score and the slug for `read_doc`. Accepts API paths and error codes. |
| `read_doc` | Read one document, or one section of it, as Markdown with current prices and limits. |
| `list_docs` | List the documents, optionally by type or product. |
| `get_product_info` | Everything about one product, with its current prices. |
| `get_api_reference` | Reference of one REST or WebSocket endpoint, or the list of endpoints. |
| `get_pricing_info` | Current prices in credits, text to speech multipliers, credit purchase prices and plans. |
| `get_usage_limits` | Enforced limits: text length, rate limits, concurrency, file sizes, Audio Studio limits. |
| `get_error_help` | Meaning, cause and fix of an error code, HTTP status or WebSocket close code. |
| `get_workflow` | Step-by-step instructions for a common task, or the list of workflows. |

## Voices (`voices`)

| Tool | Purpose | Notes |
| --- | --- | --- |
| `list_voices` | List the voices the user can use: their own, their team's and public ones. Each has an `engine` and `badges`. Pass `language` (for example `ar`) for names and badges in that language; voices without it fall back to English. | Free, every plan |
| `play_voice_sample` | Show a player for a voice's sample clip so the user can hear it. | Free, every plan |

## Cost and balance (`cost`)

All free and read-only.

| Tool | Purpose | Notes |
| --- | --- | --- |
| `get_balance` | The user's credit balance. | Every plan |
| `check_credits` | Whether a given number of credits is affordable. | Every plan |
| `estimate_text_to_speech` | Credits to voice a text with a given voice and mode. | Every plan |
| `estimate_project_generation` | Credits to render a project, all lines or only the changed ones. | |
| `estimate_edits` | Credits to render only the edited and added lines of a project. | |
| `estimate_book_cost` | Credits for a whole PDF book: OCR, optional normalization and translation, and speech. | |

## Speech and jobs (`generation`)

| Tool | Purpose | Notes |
| --- | --- | --- |
| `text_to_speech` | Generate speech from text with no project. Returns a `job_ref`. | Billable, every plan |
| `create_audiobook` | One call: create a project, set its voice, estimate, and start rendering if confirmed. | Billable |
| `generate_audio` | Render a whole project or one chapter. `missing` renders only lines without audio, `all` renders everything again. | Billable |
| `generate_lines` | Render specific lines by id. | Billable |
| `transcribe_audio` | Transcribe an audio file to text. | Billable |
| `get_job` | Poll a job until `is_terminal`. | Free, every plan |
| `get_job_result` | The URL of a finished job's output. | Free, every plan |
| `download_result` | Deprecated alias of `get_job_result`. | Free, every plan |
| `get_line_audio` | URLs of the rendered audio of lines. | Free |
| `get_chapter_audio` | URL of a chapter's merged audio. | Free |
| `merge_chapters_audio` | Merge rendered chapters into one MP3. | Free |
| `merge_chapters_subtitle` | Merge the chapters' subtitles into one SRT or VTT file. | Free |
| `export_wav` | Export rendered audio as WAV, built in the background. | Free |
| `play_audio`, `play_line` | Show or return audio for listening in the assistant. | Free |

## Projects (`projects`)

| Tool | Purpose | Notes |
| --- | --- | --- |
| `list_projects` | The user's Audio Studio projects, newest first. | Free |
| `get_project` | A project's overview: chapters with line and character counts, without line text. | Free |
| `get_chapter` | One chapter with its lines. | Free |
| `create_project` | Create a project from a document, from text, or empty. A document import returns a `job_ref`. | Free to create; OCR and other processing can be billable |
| `delete_project` | Delete a project. Needs confirmation. | Free |

## Authoring (`authoring`)

All free. A mode or voice set here affects what a later render costs.

| Tool | Purpose |
| --- | --- |
| `add_chapter`, `rename_chapter`, `reorder_chapters`, `delete_chapter` | Manage chapters. Deleting needs confirmation. |
| `add_line`, `add_lines`, `update_line`, `update_lines`, `reorder_lines`, `delete_line` | Manage lines. `add_lines` and `update_lines` are batch tools; use them instead of loops. Deleting needs confirmation. |
| `set_project_voice` | Set a project's default voice, mode, context or content language. |
| `set_line_voice_settings` | Override voice settings for one line. |
| `set_line_qa_status` | Set a line's review status. |
| `run_ai_qa` | AI review of a chapter's text or rendered audio. This one is billable. |
| `get_qa_results` | Read the results of an AI review. |

## Using the tools well

- Know the state first: `list_projects`, then `get_project`, then `get_chapter` only for the chapters you need.
- Edit in batches with `update_lines`.
- Never invent a voice id. Take it from `list_voices`, and let the user hear it with `play_voice_sample`.
- Estimate before every billable call, show the estimate, and wait for the user's approval.
- After a billable call, poll `get_job`, then confirm success with `get_job_result`.

The complete procedure for a book is in [Create an audiobook](../workflows/audiobook.md).
