Skip to main content
Glama

narrador

by io.narrador
OverviewDiscussionsAdmin

Create Files TTS Job

create_files_job

Creates a narrador files TTS job and returns jobId (uuid). Accepts either plain text (up to 500,000 characters) or an uploaded file reference. When passing text, fileName is optional (defaults to document.txt). When passing fileId, fileName is required. The job processes asynchronously: poll get_files_job until status is 'completed', then fetch audio with get_files_result. Consumes user credits. Not idempotent (creates a new job each time). Requires narrador:files scope (OAuth) or nrd_files_* API key. Use list_voices to get valid voiceId values.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
textNoPlain text content to convert to speech (1-500,000 characters). Mutually exclusive with fileId. If provided, fileName is optional.
accentYesAccent/language code (e.g. 'en-us', 'es-mx', 'fr-fr'). Must match one of the supported accent codes. Use the voice's defaultAccent if unsure.
fileIdNoUUID of a previously uploaded file. Mutually exclusive with text. When provided, fileName is required.
voiceIdYesTTS voice UUID from list_voices. Determines the speaker for audio generation.
fileNameNoFile name for the job (1-200 characters). Required when using fileId. Optional when using text (defaults to document.txt).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / accent / description
      Added value: +"Accent/language code (e.g. 'en-us', 'es-mx', 'fr-fr'). Must match one of the supported accent codes. Use the voice's defaultAccent if unsure."
    • addedInput schema / properties / fileId / description
      Added value: +"UUID of a previously uploaded file. Mutually exclusive with text. When provided, fileName is required."
    • addedInput schema / properties / fileName / description
      Added value: +"File name for the job (1-200 characters). Required when using fileId. Optional when using text (defaults to document.txt)."
    • addedInput schema / properties / text / description
      Added value: +"Plain text content to convert to speech (1-500,000 characters). Mutually exclusive with fileId. If provided, fileName is optional."
    • addedInput schema / properties / voiceId / description
      Added value: +"TTS voice UUID from list_voices. Determines the speaker for audio generation."
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses that the job runs asynchronously (and how to poll), that it consumes user credits, the required narrador:files scope / nrd_files_* API key, and that each call creates a new job. None of this is available in the annotations, which only cover read/write/idempotency flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return value, then layered with the input branches, async flow, and auth requirements. Every sentence carries actionable information with no filler, despite covering five parameters and three related siblings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an async, credit-consuming, non-idempotent job-creation tool with no output schema, the description supplies everything needed: the return value, the polling/result workflow, auth scope, and the input-mode decision. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already fully documented, including the text/fileId exclusivity, fileName conditionality, and the 500,000-character limit. The description restates those same constraints rather than adding new meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Creates a narrador files TTS job'), names the return value (jobId uuid), and distinguishes itself from siblings by naming get_files_job, get_files_result, and list_voices. An agent can identify the tool's role without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use routing: poll get_files_job until status is 'completed', then fetch audio with get_files_result, and use list_voices to obtain valid voiceId values. It also states the mutually exclusive text-vs-fileId branches, so the agent knows exactly which path to take.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All narrador toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources