narrador

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

Goes well beyond annotations by disclosing credit consumption, OAuth scope / API key requirements, asynchronous processing, the non-idempotent behavior, and a concrete failure mode (failed_file_processing). It also explains the deterministic voice-selection fallback chain when voiceId/accent are omitted, which the annotations cannot convey.

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?

Front-loaded with purpose and return value, then the operational guidance, with no filler sentences. It is dense and packs multiple clauses per sentence, which slightly hurts scanability but every clause carries actionable information.

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, but the description compensates by naming the returned jobId and describing the async follow-up calls needed to obtain results. Auth, credits, failure modes, and voice-selection behavior are all covered, leaving nothing essential for a correct invocation.

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 coverage is 100% and the parameter descriptions already restate the mutual-exclusivity, fileName-required-with-fileId, and both-or-neither accent/voiceId rules almost verbatim. The description thus adds little beyond the schema; a baseline 3 is appropriate for a fully documented 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+resource ('Creates a narrador files TTS job') and immediately names the return value ('returns jobId (uuid)'). It is clearly distinguishable from the sibling read tools get_files_job and get_files_result, which it explicitly routes to.

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?

Gives an explicit end-to-end workflow: poll get_files_job until status is 'completed', then fetch audio with get_files_result, and use list_voices to pick a voice explicitly. It also names the condition that selects each input mode (text vs fileId) and when to supply voiceId/accent.

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?

Annotations cover safety (readOnly=false, idempotent=false, destructive=false), and the description adds genuinely new behavior: credit consumption billed like the narrador X app, 403 on insufficient credits or wrong key scope, the cached-immediate vs synchronous generation model, and the required narration scope/API key form.

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?

Front-loaded with purpose and return values, then auth/credit/polling details. Every sentence carries information, though the density of parenthetical asides (four-tuple return list, scope formats) makes it slightly heavier than ideal.

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?

With no output schema, the description compensates by naming the returned fields (generationId, audioUrl, duration, wordTimings) and explaining the async polling path, auth requirements, and credit model. An agent has everything needed to call it and handle the response.

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 already 100%, so the baseline is 3; the description adds value by tying voiceId to list_voices with product `x`, which the schema does not state, and by reiterating the postId/postUrl mutual exclusivity. It adds modest but real guidance beyond 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 and resource ('Generates narrador X audio for a social media post') and enumerates the concrete outputs returned. It also distinguishes itself from the sibling tool set by contrasting with 'narrador files' and naming the follow-up tool get_x_generation.

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?

Explicitly routes the agent: poll get_x_generation when generation is slow, and use list_voices with product `x` to obtain voiceId values. It also states the postId/postUrl alternative inputs and the credit/scope preconditions, so both when-to-use and how-to-follow-up are covered.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally; the description still adds real context by stating it does not consume credits and that OAuth or API key authentication is required. It does not cover error behavior or failure modes under missing auth, keeping it below 5.

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?

Four tight sentences with no filler: return contents first, then the read-only/no-credit-cost constraint, then auth requirements, then the actionable usage hint. It is front-loaded with what the agent most needs to know.

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?

With no output schema, the description carries the burden of describing returns and does so reasonably – identity, products, app, and credit balances – plus auth and credit-cost behavior. Minor gaps remain around error/auth-failure behavior and whether 'app' is null for user tokens versus populated for API keys is fully spelled out.

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 the baseline is 4. The description stays focused on returned fields rather than inventing parameter semantics, which is appropriate for an argument-free call.

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+resource ('Returns authenticated user identity') and then enumerates the exact payload: products, nullable app for API keys, and credit balances. The response shape reference ('same shape as GET /v1/me') pins down semantics precisely, and none of the sibling tools (job/generation/voice tools) could be confused with an account lookup.

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?

Gives a clear usage context – 'Check credit balance before creating jobs or generations' – which ties this tool to the sibling job/generation tools in a meaningful workflow. It stops short of naming explicit alternatives or when-not-to-use conditions, so it is clear context rather than full routing 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?

Annotations already declare readOnlyHint and idempotentHint, so the description's 'Read-only operation' is redundant, but it adds genuinely new context: the polling pattern, the concrete status values, the 0-100 progress range, and the required narrador:files scope or nrd_files_* API key. This is well beyond annotation coverage, though the auth detail could note failure behavior.

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?

Four front-loaded sentences where each earns its place: purpose, usage sequence, return fields, and auth requirement. No filler or repetition.

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?

With no output schema, the description compensates by enumerating the return fields (jobId, status, progressPercentage, audioId), and it covers the polling lifecycle and auth prerequisites. An agent has everything needed to call and interpret this tool correctly.

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 jobId param is fully documented in the schema (including the 'snapshot id' alias), so the description adds no parameter-level syntax beyond what the schema provides. Baseline 3 is appropriate.

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 ('Returns narrador files job status and progress') and distinguishes itself from siblings by naming create_files_job and get_files_result in its workflow. An agent can immediately tell this is the polling status endpoint.

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?

Explicitly says to poll after create_files_job until status is 'completed', and directs the agent to get_files_result once audioId is present. Both the when-to-use and the alternative/next step are named, so nothing is left to inference.

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?

Beyond the readOnly/idempotent annotations, it discloses the failure mode (precondition error when audio is not ready), the auth requirements (narrador:files OAuth scope or nrd_files_* API key), and field-level nullability (duration may be null). This is real behavioral context an agent needs before calling.

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?

Front-loaded with purpose then return shape, with prerequisites and auth at the end. The enumeration of return fields is justified since no output schema exists, though 'Read-only operation' overlaps the annotations and is slightly redundant.

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?

With no output schema, the description fully specifies the return payload (jobId, audioUrl, audioId, duration, wordTimings and their sub-fields), plus preconditions and auth. An agent has everything needed to call and interpret this tool correctly.

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 there is only one parameter, so the schema already documents jobId fully. The description's mention of jobId comes in the context of return values rather than adding input semantics, 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?

States a specific verb and resource ('Fetches completed narrador files job audio and metadata') and names the exact payload returned. It is clearly distinguishable from the sibling get_files_job, which only reports job state.

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?

Gives an explicit precondition ('Only succeeds when job status is completed') and an explicit alternative to call first ('Call get_files_job first to confirm the job is completed'). Nothing is left to inference about when to invoke this tool.

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 annotations already covering readOnly/idempotent/destructive, the description goes further: it discloses the ownership scoping rule ('only generations linked to your account'), the 404 and 403 failure modes, and the required scope/API key format. This is exactly the behavioral context annotations cannot express.

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?

Dense but front-loaded with the return shape before the operational caveats. Slightly redundant with 'Read-only operation,' which merely restates the readOnlyHint annotation, but overall every other sentence earns its place.

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?

In the absence of an output schema, the description fully documents the return structure (generationId, audioUrl, duration, wordTimings and their sub-fields) and covers auth and error semantics. Nothing an agent needs to invoke and interpret this call 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?

Schema coverage is 100% and the single generationId parameter is fully documented in the schema, so the description need not repeat it. Baseline 3 applies; the description adds no format or syntax detail beyond 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?

Opens with a specific verb+resource ('Fetches narrador X generation audio and metadata') and immediately enumerates the returned fields. An agent can distinguish this from the sibling generate_x_audio without opening a schema.

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?

Explicitly routes usage: 'retrieve a generation if generate_x_audio was called earlier or to re-fetch audio,' tying it to a named sibling tool. It gives clear context but no explicit when-not-to-use case or alternative retriever.

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?

Annotations already declare read-only/idempotent, and the description still adds real behavioral context beyond them: the 403 on missing product scope, sampleUrl auth behavior (public 302, no API key), and a deprecation notice for `provider`. This is materially more than the annotations provide.

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?

Front-loaded with purpose and the product-selection rule, then return fields, deprecation, and a usage pointer. Dense and mostly earning its space, though the product default is restated from the schema, adding slight redundancy.

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?

No output schema exists, yet the description enumerates the returned fields (id, name, tier, defaultAccent, isPublic, description, sampleUrl) and their semantics, including the tier values. An agent has everything needed to call and interpret the result.

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 coverage is 100% and the enum is documented, so the schema does most of the work. The description nonetheless adds the failure condition (403) and reiterates the default resolution rule, which is useful but partly redundant with the schema's own description.

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 ('returns voices for narrador files or narrador X') and immediately distinguishes the two catalogs. An agent can tell what it gets and how the two product variants differ without consulting the schema.

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?

Explains exactly when `product` matters ('when your token has both products'), what happens otherwise (403), and downstream usage ('Use a voice id when calling create_files_job or generate_x_audio'), naming concrete siblings. No inference required.

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