> ## Documentation Index > Fetch the complete documentation index at: https://docs.jogg.ai/llms.txt > Use this file to discover all available pages before exploring further. # Tools, Billing, and Safety > Understand JoggAI MCP tool discovery, paid generation, asynchronous jobs, uploads, approvals, and Space isolation. JoggAI MCP exposes explicitly registered OpenAPI v2 operations as tools. The exact scope-filtered list is returned by `tools/list`; clients should not assume a fixed tool count. New REST endpoints do not become MCP tools automatically. Legacy `/open` and `/open/v1` operations are not exposed. ## Tool groups | Group | Examples | Typical scope | | - | - | - | | Account | Account details and remaining quota | `account.read`, `quota.read` | | Catalog | Avatars, voices, music, templates, and styles | `catalog.read` | | Assets | Signed upload requests | `asset.write` | | Scripts | Script submission and result lookup | `script.generate` | | Speech | Speech synthesis and task lookup | `voice.generate` | | Avatars and images | Photo and product avatar generation | `image.generate`, `video.generate` | | Video | Avatar, product, template, lip sync, and translation jobs | `video.generate` | | Products | Product records, previews, and results | `product.read`, `product.write` | | Webhooks | Event discovery and endpoint management | `webhook.read`, `webhook.write` | Tool names and input JSON Schemas come from the JoggAI OpenAPI v2 contract. The agent should use the schema returned by `tools/list` instead of inventing REST paths or fields. ## Paid tools Generation tools can consume the selected Space's existing JoggAI credits. There is no separate MCP balance or MCP surcharge. Every credit-consuming tool includes a billing warning in its description and is marked with a destructive hint so compatible clients can request confirmation. Examples include: * AI scripts and avatar images * Speech synthesis * Avatar motion and lip sync * Avatar, product, preview, and template video generation * Video translation > [!WARNING] > > An OAuth scope is permission to call a tool, not approval for a particular > charge. Review the tool name, billing warning, Space, duration, image count, > preview count, and other cost-driving inputs before confirming. Read-only status tools do not resubmit work. When retrying after a timeout, query the existing task ID before creating another paid task. > [!WARNING] > > MCP transport retries are not a billing idempotency guarantee. If a paid submit > call times out before returning a task ID, do not replay it automatically. Some > tools accept an explicit idempotency key; otherwise inspect the matching list or > status tool, then contact support if the outcome is still unknown. ## Speech model selection The `jogg_post_audio_tts_synthesize` tool accepts optional `body.model_id` for ElevenLabs voices. Select `eleven_flash_v2_5` or `eleven_v4_turbo`; omitting the field uses `eleven_flash_v2_5`. Empty strings, whitespace, `null`, non-string values, and other model IDs are rejected. For a voice from another provider, omit `model_id` to preserve its existing behavior. Explicitly selecting either ElevenLabs model for that voice is rejected. The default in `tools/list` describes ElevenLabs behavior; clients should not add the field automatically when the user has not selected a model. Jogg adapts pause controls in a copy when sending the synthesis request and keeps the original text. For `eleven_v4_turbo`, timed breaks greater than 0 and up to 0.5 seconds become `[short pause]`; breaks over 0.5 and up to 1 second become `[pause]`; longer breaks, including those over 2 seconds, become `[long pause]`. Zero-second breaks are removed, and supported millisecond values are converted to seconds first. For Flash, `[short pause]`, `[pause]`, and `[long pause]` become SSML breaks of 0.3, 0.75, and 1.5 seconds respectively. These are Jogg compatibility rules, not exact duration equivalents specified by ElevenLabs. Flash preserves other bracketed text; delivery tags such as `[whispers]` need v4 Turbo. New v4 Turbo subtitles omit complete square-bracket audio tags and break tags. When adapting v4 pause tags for Flash, subtitles omit those controls and their converted breaks while retaining other bracketed text. These v4 compatibility paths split words at explicit pauses and preserve the returned timing gap. Native Flash breaks continue to use the existing subtitle processing. The input-text fallback uses the same model-specific filtering when word timestamps are unavailable; control-only text has no subtitle content. Existing subtitles are not rewritten. To select v4 Turbo, pass these `tools/call` parameters: ```json theme={null} { "name": "jogg_post_audio_tts_synthesize", "arguments": { "body": { "text": "Hello from JoggAI.", "voice_id": "YOUR_ELEVENLABS_VOICE_ID", "model_id": "eleven_v4_turbo", "idempotency_key": "speech-example-turbo" } } } ``` To use Flash v2.5 by default, remove `model_id`. Keep a stable `idempotency_key` when retrying the unchanged request. Changing an explicit model with the same key causes a conflict; use a new key for a new synthesis. When the task ID is known, use `jogg_get_audio_tts_tasks_task_id` to check its status without another paid submission. See [Synthesize Speech](https://docs.jogg.ai/api-reference/v2/Voice/SynthesizeSpeech.md) for the REST API request. Native text controls also depend on the model: Flash v2.5 accepts SSML `` (up to 3 seconds), while v4 Turbo uses square-bracket audio tags such as `[whispers]` or `[short pause]` and does not support SSML breaks. Flash does not support those audio tags. Put the instructions in `body.text`; pause tags have no fixed duration in seconds. See the [model comparison, examples, and official ElevenLabs sources](https://docs.jogg.ai/api-reference/v2/Voice/SynthesizeSpeech.md#pauses-and-audio-tags) before switching text controls between models. ## Asynchronous jobs Generation submissions normally return a task or resource ID. A robust agent workflow is: **1. Review inputs and billing warning** Confirm the selected Space and cost-driving parameters before submission. **2. Submit once** Store the returned task, video, generation, or preview ID. **3. Poll the matching status tool** Continue until the job completes or returns a terminal failure. **4. Reuse the existing result** Do not create a duplicate because a client connection or polling request timed out. ## Uploads MCP JSON-RPC requests do not carry large media files. An upload tool returns a short-lived signed URL, method, and required headers. Upload the bytes directly to object storage, then pass the resulting asset reference to another tool. Treat signed URLs as credentials. Do not log, publish, or reuse an expired URL. ## Space and resource isolation Authorization binds the session to a JoggAI user and selected Space. Private avatars, images, products, generation tasks, and other resources must belong to that authorized context. Knowing another resource ID does not grant access. Team members use the Space's actual billing account for quota checks and paid operations. If Space membership, ownership, or plan eligibility changes, an existing token may stop authorizing calls. ## Webhooks and external effects Creating, updating, or deleting webhook endpoints changes where JoggAI sends events. Confirm the destination domain and selected endpoint before a write or delete. Never send authorization headers, OAuth tokens, or signed asset URLs to a webhook destination. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.