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

Annotations include readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds useful detail about pause behavior but does not disclose whether existing clips are altered, whether output files are overwritten, or other side effects. No contradiction with annotations, but the openWorldHint is not clarified.

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?

The description is two sentences, front-loaded, and every clause is informative. It avoids fluff and directly gives operational instructions for ordering and pause durations.

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?

The description covers core usage and the tricky pause_durations parameter, but it omits information about filename/output_dir semantics and does not describe the output format. For a tool with 4 parameters and no output schema, this is a moderate 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 description explains clip_ids ordering and pause_durations format in detail, supplementing the schema descriptions. However, filename and output_dir are not described in the schema nor in the description, leaving two of four parameters semantically under-specified.

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 uses a specific verb ('Merge') and resource ('existing clips') and clearly states the outcome ('single audio file'). This distinguishes it from sibling tools like list_clips or generate_speech, which do not combine existing clips.

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 gives clear context: combine existing clips in order, with optional pauses. It does not explicitly name alternatives or state when not to use it, but the phrase 'existing clips' implicitly separates it from generation tools.

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?

The annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) already set the safety profile. The description adds valuable context by stating the return value is a raw job record and that the render is asynchronous, which goes beyond the annotations without contradicting them.

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 sentences with all content earning its place. The action, usage context, polling step, and return type are efficiently packed. No verbosity 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?

For a job-starting tool with no output schema, the description explains the async behavior, return status, and next-step polling. It lacks parameter details and potential side effects, but given the annotations and schema, it is reasonably complete. Could be improved by mentioning model/library_ids options.

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 only 50% (text and speaker_id have descriptions; model and library_ids do not). The description does not mention any parameters or compensate for the undocumented ones, leaving library_ids completely unexplained. This is a clear gap.

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 clearly states the tool starts an asynchronous TTS render and returns the clip id/status. It is distinct from synchronous generation, though it does not explicitly contrast with wellsaid_generate_speech. The verb 'start' and 'asynchronous' make the purpose specific.

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 says to use it for long or batched jobs and instructs polling with wellsaid_get_clip. This provides clear context and an alternative, though it does not explicitly say when not to use it (e.g., for short jobs), so it falls short of a full 5.

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 only indicate read/write and open-world hints. The description adds significant behavioral context: the 1000-character limit (including markup), that prosody parameters wrap text in AI Director tags and force the caruso model, that text becomes literal (escaped) when prosody is used, and that inline tags should not be mixed with prosody. This goes far beyond what 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?

The description is concise and front-loaded: the first sentence states the core purpose, the word 'Synchronous' is a compact critical qualifier, and the remaining sentences cover the essential caveats (length limit, prosody behavior, inline tag handling) without redundant filler. Every sentence contributes distinct 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?

With 12 parameters, no output schema, and no explicit return type, the description covers the essential operational context: synchronization, disk output, character limit, and the prosody/tag interaction. It does not describe the response payload, but it does mention optional inline base64 audio (embed_audio) and the file-saving behavior, which partially compensates for the missing output schema.

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?

While the schema covers 100% of parameters with descriptions, the tool description adds crucial meaning: that pitch/tempo/loudness force the caruso model and cause the text to be treated as literal (escaping special characters), and that inline tags require leaving those parameters unset. This clarifies interactions not fully captured in 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?

The description opens with a specific verb+resource: 'Convert text to speech with a WellSaid voice and save it to disk.' It also explicitly states 'Synchronous,' which distinguishes it from the async sibling wellsaid_create_clip_async, and its focus on direct speech generation differentiates it from wellsaid_generate_speech_with_timing.

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 clear usage context: it is synchronous, requires obtaining a speaker_id from wellsaid_list_voices first, and explains when to avoid passing prosody parameters (if hand-authoring inline tags). It does not explicitly name alternative tools but gives strong contextual guidance and exclusions for the main usage pattern.

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?

The description discloses that the API returns a zip containing audio, JSON timing, SRT, and VTT, and that the tool extracts and saves each file. This goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by specifying the actual write behavior and output artifacts, providing useful context.

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?

The description is three sentences, front-loaded with the primary purpose. Each sentence adds value: purpose, extraction behavior, and compatibility note. There is no fluff or repetition of schema fields.

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?

The description covers the core behavior and artifact types but lacks information about return values (since there is no output schema) and relies on the sibling for parameter details. It does not mention what happens after saving (e.g., returns file paths or nothing), leaving a gap for a complex 11-parameter tool.

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 low (45%), so the description must compensate for undocumented parameters. However, it only references 'the same voice/model/prosody options as wellsaid_generate_speech' without explaining any specific parameters or their semantics. It does not add meaning beyond the schema for most of the 11 parameters.

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 clearly states the tool renders text to speech and additionally provides word-level timing and caption files. It distinguishes itself from the sibling wellsaid_generate_speech by explicitly mentioning the timing/caption extraction and referencing the sibling for option compatibility.

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 implies this tool is the right choice when timing/captions are needed by saying 'and also get word-level timing and caption files.' It also references the sibling 'wellsaid_generate_speech' for option compatibility, but does not explicitly state when not to use it or contrast alternatives beyond that sibling.

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=true, and the description adds conditional disk-writing behavior, which is a local side effect not covered by annotations. It discloses when download happens and the dependency on API response shape ('when the API returns a URL or audio payload'), providing valuable context beyond annotations.

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 sentences, front-loaded with the primary action. No redundant phrases or filler; every word 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?

The description covers core fetch and conditional download behavior, but lacks guidance on return value/status, error handling, or the role of filename/output_dir. Without an output schema, the agent is left guessing the response format and how to use the optional parameters.

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 descriptions cover clip_id and download, but filename and output_dir have no descriptions. The description does not explain these parameters or their defaults; it only mentions 'save its audio to disk' without specifying the filename/output_dir semantics. This leaves 50% of parameters under-specified.

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 'Fetch the status/metadata of a clip by id' – a specific verb and resource with clear scope. The conditional download behavior is also described. This clearly distinguishes from sibling 'wellsaid_list_clips', which lists clips, and 'wellsaid_create_clip_async', which creates them.

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?

Implies usage from 'by id' and references 'wellsaid_create_clip_async' in the schema, indicating it's for a single clip from creation. However, it does not explicitly contrast with alternatives like 'wellsaid_list_clips' or state when download should or should not be used.

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=true and openWorldHint=true, covering the safety profile. The description adds valuable behavioral context by explaining that the output is intended for a specific tag format, which is beyond what annotations provide. It does not contradict annotations.

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 sentences, no filler. The first sentence states the action and target, the second explains how to use the result. Information is front-loaded and every 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?

For a simple one-parameter lookup tool with no output schema, the description covers purpose and usage sufficiently. It could elaborate on the exact return format (e.g., whether it returns a single string or a list), but the included example makes the expected output clear enough for an agent to invoke it 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 coverage is 100% because the single 'word' parameter has a description ('The word or term to look up.'). The tool description adds no further parameter semantics beyond restating that it's for a word, so it meets the baseline for high schema coverage.

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 action ('Get WellSaid respelling suggestions') and identifies the resource (a word), which clearly distinguishes it from sibling tools focused on voices, clips, and speech generation. It is not a tautology and provides concrete use context.

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 gives a clear usage context: use the returned value in an inline AI Director tag to control pronunciation. It does not explicitly name alternatives or exclusion criteria, but the guidance is sufficient for a unique lookup tool with no overlapping siblings.

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=true, so the description does not need to cover safety. It adds the account scope and returned fields, and the 'recent' scoping implies time-based ordering. However, it does not mention any additional behavior, such as whether results are limited by default or if there is pagination, beyond what the schema's limit parameter already states.

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?

The description is a single, front-loaded sentence that includes the action, the resource, and a parenthetical list of returned fields. There is no redundancy or unnecessary detail, making it highly 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 simple list tool with one optional parameter and read-only annotations, the description is complete enough. It names the resource, scope, and returned fields, and the absence of an output schema means the description does not need to detail return formats. A minor gap is the lack of clarification on the default limit or ordering, but this is acceptable given the simplicity.

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 input schema has 100% coverage for the single parameter 'limit', which is well-described. The tool description does not add any additional meaning to parameters beyond what the schema already provides, so the baseline score of 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 clearly states the verb 'List', the resource 'recent clips', and the scope 'on the account', along with the specific fields returned (id, status, metadata). This distinguishes it from sibling list tools like wellsaid_list_voices, which focus on different resources.

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 makes the tool's purpose unambiguous: it is for listing clips, not for other actions like generation or combining. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5 but is clear enough for an agent.

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 include readOnlyHint: true and openWorldHint: true, so the tool is known to be read-only and open-world. The description adds behavioral scope by stating it summarizes distinct attributes 'across all voices', which clarifies the aggregation behavior. It does not describe return format, but with zero parameters and a simple summarization role, this is acceptable.

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?

The description is a single sentence that leads with the action ('Summarize'), lists the specific criteria, and closes with a practical use case. Every phrase contributes meaning with no wasted words.

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?

Given the tool's simplicity (no parameters, no output schema, read-only aggregation), the description fully covers what the tool does and why it is useful. It is complete and self-contained.

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?

There are zero parameters, and the schema coverage is 100% as it is empty. The description does not need to add parameter details, and according to the rubric, a zero-parameter tool gets a baseline of 4.

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 uses the specific verb 'summarize' and identifies the resource (styles, accents, genders, languages, characteristics across all voices), clearly distinguishing it from the sibling tool wellsaid_list_voices which lists voices themselves.

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 states it is 'useful for narrowing a wellsaid_list_voices search', giving a clear context for when to use this tool. It does not mention exclusions or alternative tools, but the pointer to wellsaid_list_voices is sufficient 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 mark it read-only, so the bar is lower. The description adds value by disclosing that fields like name, style, accent, gender, and language are returned 'when the API provides them,' acknowledging potential data variability. It also implies a caching mechanism via the refresh parameter (though not in the description itself), but does not mention rate limits or other behaviors.

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?

The description is two sentences, front-loaded with the primary action, followed by essential output details and filter capability. Every sentence earns its place with no redundancy or fluff.

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 simple list tool with readOnlyHint and full schema coverage, the description is sufficiently complete: it states what is returned, the optional filter, and the connection to speech generation. It lacks only explicit mention of pagination/limit behavior, but the schema covers that. Given the tool's simplicity and available annotations, this is adequate.

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 baseline is 3. The description repeats the search filter concept but adds no new semantics beyond the schema. It does not explain limit or refresh beyond what the schema already does, so no additional value is provided.

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 opens with 'List the available WellSaid voice avatars' — a specific verb and resource. It further clarifies the tool's role by stating it returns speaker_id (the value passed to wellsaid_generate_speech), which distinguishes it from sibling tools like wellsaid_list_voice_criteria.

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 gives clear context by linking the output to wellsaid_generate_speech, implying this tool is for selecting voices for speech generation. It does not explicitly state when not to use it or list alternatives (e.g., wellsaid_list_voice_criteria), but the context is sufficient for most use cases.

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?

Adds useful behavior beyond annotations: authenticated requests, JSON responses as text, binary responses saved to disk with save_as. This complements the openWorldHint annotation by describing concrete response handling, though it doesn't cover all edge cases.

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 sentences, front-loaded with purpose, then response handling. Every word earns its place; no fluff.

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?

The description covers the core behavior and response handling, but with 7 parameters and no output schema, it lacks details on error handling, authentication specifics, and the role of output_dir. It's adequate for an advanced escape hatch but has clear gaps.

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 86%, so the schema already explains most parameters. The description adds context about save_as for binary saving, but leaves output_dir undocumented in both schema and description. Overall, it offers some added value but doesn't fully compensate for the coverage gap.

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?

Description clearly identifies it as an escape hatch for endpoints without a dedicated tool, distinguishing it from siblings. The specific verb 'makes an authenticated request' plus 'any path under the API base' defines the scope precisely.

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 states when to use: 'for endpoints without a dedicated tool' (e.g. replacement libraries). This implies not using when a dedicated tool exists, providing clear guidance.

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