narrador

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

With no annotations, the description carries the full behavioral burden. "Start a ... job" implies an async, fire-and-forget operation, but it never says what is returned (job ID?), that the result must be retrieved later, or whether anything is overwritten or costs credits. Sibling tools get_files_job and get_files_result hint at a polling lifecycle that the description fails to mention.

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

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

Two compact sentences with the core action front-loaded and the parameter requirements immediately after. Nothing is padded, though the second sentence is dense and could be split for readability.

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

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

For a 5-parameter mutation tool with no annotations and no output schema, the description is thin: it omits the async job lifecycle, how to fetch results, and any auth or limit context. An agent knows how to call it but not what happens after the call.

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

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

At 0% schema description coverage for 5 parameters, the description must compensate, and it does add real value by defining the mutually exclusive input modes: text (+optional fileName) versus fileId + fileName. However, accent and voiceId semantics are left unexplained (no enum, no pointer to list_voices for voiceId), and the schema's uuid formats go unmentioned.

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

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

States a specific verb and resource: "Start a narrador files audio job." The "files" qualifier implicitly separates it from the sibling generate_x_audio, but the description never names that sibling, so an agent must infer the distinction. Clear but no explicit sibling differentiation.

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

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

The description explains how to fill in parameters ("either text (+ optional fileName) or fileId + fileName") but gives no guidance on when to pick this tool over generate_x_audio, nor when the text branch is preferable to the fileId branch. It reads as a parameter spec, not usage guidance.

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

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

With no annotations, the description carries the full disclosure burden. It does not state whether this is an async job (siblings get_files_job/get_files_result suggest a polling pattern), where the resulting audio is retrieved, whether it costs credits or is rate limited, or whether the operation is idempotent.

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

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

Two short sentences, purpose first and parameter guidance second, with no filler. It is appropriately sized for the tool, though the second sentence could be tightened by explaining 'either/or' as mutually exclusive.

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

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

For a generation tool with no annotations, no output schema, and 0% parameter documentation, the description omits critical completion information: result retrieval, async vs sync behavior, and voice selection prerequisites. What is present is accurate but too thin given the total absence of structured support.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does: it flags accent as optional and expresses the 'either postId or postUrl' relationship that the schema does not encode (the schema would allow both or neither). It still says nothing about what a voiceId is, that it is a UUID sourced from list_voices, or what values accent accepts.

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

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

States a verb (Generate) and a resource (narrador X audio for a post), which distinguishes it from read-oriented siblings like get_x_generation and list_voices. However, the jargon 'narrador X audio' is unexplained, so an agent cannot be fully certain whether this is a voiceover for an X/Twitter post or something else.

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

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

There is no when-to-use guidance, no prerequisite chain (e.g. call list_voices first to obtain a voiceId), and no mention of when this tool is preferable to the generation/fetch siblings. The only routing hint, 'either postId or postUrl', is invocation detail rather than usage context.

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

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

With no annotations, the description carries the full behavioral burden. Read-only behavior is only implied, and it does not state whether the key's product scope affects other calls, whether credit data is live, or any rate/permission constraints. The mention of 'API key product scope (files or x)' is the only real behavioral signal.

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

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

A single compact sentence with no filler, and the most useful field (product scope/credits) is included up front. It is terse but not padded, and the nominal phrasing is slightly less scannable than a verb-led sentence.

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

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

For a zero-parameter, read-only account lookup with no output schema, the description covers the key return items (identity, key scope, balances), which is sufficient for an agent to know what to expect. It stops short of stating format or guaranteed fields, but nothing essential is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. Schema coverage is also reported at 100%.

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

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

The description names a specific resource (account) and enumerates the exact contents returned: identity, API key product scope (files or x), and credit balances. It clearly distinguishes this zero-argument read from all six sibling job/generation/voice tools, though it lacks an explicit verb like 'retrieve'.

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

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

There is no statement of when to call this versus alternatives, no prerequisites, and no conditions. The intended use (checking identity, key scope, or credits) is only inferable from the returned-field list.

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

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

With no annotations, the description carries the full burden. It usefully discloses that this is a polling read that reports status and progress, but says nothing about rate limits, whether it blocks, or what fields the status/progress payload contains.

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

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

Two short sentences, zero filler, with the purpose front-loaded ahead of the parameter note. Nothing to trim.

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

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

For a one-parameter polling tool with no annotations and no output schema, the definition covers the essentials but omits the return shape (what 'status and progress' actually looks like), which the absent output schema would otherwise supply.

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

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

Schema description coverage is 100% and the single parameter already documents the uuid format and its origin ('returned by create_files_job'). The description's 'Requires jobId (uuid)' merely restates the schema, adding no new semantics.

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

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

States a specific verb and resource ('Poll narrador files job status and progress'), which is clearly distinct from the sibling get_files_result (results vs. job status). It does not explicitly name the sibling or contrast the two, so it falls short of a 5.

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

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

'Poll' implies an iterative usage pattern (call repeatedly until the job completes), and the prerequisite jobId is stated. However, it names no alternative (e.g., when to use get_files_result instead) and gives no explicit stop condition.

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

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

No annotations are provided, so the description carries the full burden. It usefully signals that the job must be 'completed' and that a uuid jobId is mandatory, but it omits permission requirements, behavior when the job is incomplete or missing, and any polling/retry semantics. Partial behavioral disclosure.

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

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

Two short sentences, front-loaded with the action and payload before the parameter requirement. Every phrase carries information; no filler.

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

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

There is no output schema, and the description partially compensates by naming the return fields (audio URL, duration, word timings). Still missing: error behavior for incomplete jobs, how to acquire jobId, and the async polling relationship to sibling tools.

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

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

Schema description coverage is 0% and the single jobId param is only typed as uuid. The description adds the requirement and format ('Requires jobId (uuid)'), matching the schema, but does not say where jobId comes from or how it is obtained. Baseline for a one-param tool with the description mirroring the schema.

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

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

States a specific verb (Fetch), the resource (narrador files job result), and the returned payload (audio URL, duration, word timings). This distinguishes it from sibling get_files_job, which presumably returns job metadata rather than the outcome. It could name that sibling dependency explicitly, but the purpose is clear.

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

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

The word 'completed' implies this is only valid after a job finishes, which hints at the create_files_job / get_files_job workflow. However, it never states when to use this versus get_files_job, nor what to do if the job is still running. Usage is implied, not specified.

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

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

With no annotations, the description carries the full burden. It hints that the call returns both status and an audio result, but does not disclose whether this is a poll-until-complete operation, whether auth is required, how the audio result is delivered, or any rate limits. The behavioral disclosure is thin for a tool whose purpose is presumably polling.

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

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

Two short sentences with the core action front-loaded and no wasted words. It is appropriately sized, though the second sentence is pure parameter restatement rather than adding useful context.

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

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

For a single-parameter read tool with no output schema, the definition is minimally adequate. It signals that status and audio are returned, but does not explain the return structure or the expected usage flow, leaving gaps an agent would have to fill by trial.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter, its uuid format, and even notes it is "returned by generate_x_audio" - more detail than the description provides. The description merely restates "Requires generationId (uuid)", adding no meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb ("Fetch") and resource ("narrador X generation status and audio result"), which is clear enough for an agent to identify what it does. However, it does not differentiate itself from potential siblings like get_files_result or get_files_job, so an agent must infer the distinction from naming alone.

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

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

The description provides no when-to-use guidance, no prerequisites, and names no alternatives. "Requires generationId (uuid)" is a parameter requirement rather than usage context; the only implied flow is that a generationId comes from generate_x_audio, which is not stated in the description.

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

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

No annotations are provided, so the description carries the full disclosure burden. It says nothing about whether the list is account-scoped, whether it requires auth, whether results are cached, or what a voice entry contains — all of which matter for a discovery tool feeding TTS jobs.

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

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

It is a single short sentence with no filler, which is good. But the garbled 'narrador files voices' phrasing means the sentence is not cleanly parsed on first read, so it is terse rather than efficient.

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

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

For a trivial zero-parameter list tool with no output schema, the description is nearly complete but still omits the return shape (voice ids/names/locales) that an agent needs to actually select a voice for a downstream TTS job. Minimum viable, with a clear gap.

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

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

The tool takes zero parameters and the schema is an empty object, so there is no parameter semantics to explain. Baseline 4 applies; the description cannot add parameter meaning that does not exist.

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

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

The verb 'List' and resource 'voices' are identifiable, and 'available for TTS jobs' scopes it. However, the phrase 'narrador files voices' is garbled enough that an agent cannot tell what namespace or product surface these voices belong to, leaving the purpose only partially clear against siblings like generate_x_audio.

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

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

There is no indication of when to call this versus the sibling job/generation tools, no prerequisite (e.g., must a voice be selected before create_files_job), and no recommended call order. Usage must be inferred entirely.

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