leemysw/yovoice

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

With no annotations, the description carries the full burden; it does disclose two useful behaviors: cancellation is followed by polling to a terminal state, and already-terminal tasks are left unchanged (idempotent/no-op). It omits what happens on an unknown requestId, whether cancellation is reversible, and what the call returns, so disclosure is partial.

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 the action front-loaded and the follow-up polling behavior attached after the semicolon. Nothing is wasted, though the phrasing is dense enough that the post-cancellation polling instruction could be missed.

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 mutation tool with no annotations and no output schema, the description covers the action, the post-cancel state check, and idempotency on terminal tasks. It still leaves the agent unsure about failure modes (invalid/completed requestId) and return value, which matters more here because no structured fields fill that 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?

Schema coverage is 0% for the single parameter, so the description must compensate. '按 requestId' tells the agent the id identifies the task to cancel, which is the essential meaning, but gives no format, source (where to obtain the requestId), or error behavior for an invalid id.

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 verb and resource — cancel a task — and the keying parameter (requestId), which separates it cleanly from generate, submit_generation and get_generation. It stops short of explicitly contrasting itself with a sibling (e.g. get_generation for polling), so it is clear but not fully differentiated.

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 the agent should poll for a terminal state after cancelling, and '终态任务保持不变' implicitly tells the agent that cancelling a finished task is a no-op. However it never names the polling tool (status/get_generation) or states explicit preconditions such as which task states are cancellable, so usage is only implied.

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 does disclose the most important trait, namely that this is a blocking synchronous call, and it names the return values, but it says nothing about side effects on disk (whether an existing WAV file is overwritten), permissions or authentication, timeouts, or how a failure is reported.

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 short clauses, with the sync-vs-async routing rule front-loaded before the functional description and the return/path clarification last. Every clause carries information, and nothing is padded.

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 two-parameter speech-generation tool with no annotations and no output schema, the description does cover the return shape (which is good, since no output schema exists). However, it leaves the open `settings` object undefined beyond "same names as the HTTP API", so an agent cannot tell which keys are valid, and it omits blocking and timeout behavior for a call that produces a local file.

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%, with both `text` and `settings` documented in the schema, so the baseline is 3. The mention of "path" clarifies a returned field rather than an input parameter, and the nested `settings` object is described only by reference to the HTTP API, a point the description does not expand on.

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 verb and resource ("完整生成语音" / fully generate speech) and explicitly distinguishes this tool from its async sibling submit_generation through the word "同步生成" (synchronous generation). Because it also names the return fields (id, duration, audio location), an agent can select this tool over status/get_generation 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.

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

The description states the condition for choosing the alternative: "长耗时优先使用 submit_generation" tells the agent to route long-running work elsewhere. This is a clear when-to-use rule, but it does not explain what counts as "long" or how this tool relates to siblings such as get_generation or cancel_generation.

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 exist, so the description carries the full burden; it does disclose the polling cadence and the completed→download handoff, plus the local-mode variation. It omits error/failed-state behavior, whether polling is rate-limited server-side, and any auth or permission requirements.

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 the action and key front-loaded, followed by the polling and download instructions. No wasted clauses, though the parenthetical local-mode note is slightly compressed.

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 should convey the return shape; it names downloadPath and the local-mode path but never enumerates possible status values beyond 'completed', leaving the agent to guess pending/failed semantics on a polling 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 coverage is 0% for the single requestId parameter, so the description must compensate. It does explain that requestId identifies the task to query, but adds no format, origin, or validity detail (e.g., where the id comes from in generate/submit_generation).

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: query a task by requestId, which names both the action and the key it operates on. An agent can tell it apart from generate/submit_generation, though the overlap with the sibling 'status' tool is not addressed.

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 concrete operational guidance: poll every 2–5 seconds, then use downloadPath once status is completed. It stops short of stating when to prefer this over the sibling 'status' tool or what to do on failure/cancellation.

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: 查询 signals a read-only operation, and the field list (ID, install status, advanced parameters) tells the agent what comes back. It says nothing about auth requirements, whether uninstalled models are included, or result ordering/size.

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 the query scope front-loaded and the usage note after the semicolon. Dense but every clause 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?

For a zero-param listing tool with no output schema, the description does the necessary work by naming the returned fields and tying the call to the generation workflow. Output format and filtering behavior remain unspecified but are minor for a simple enumeration.

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 correctly implies a no-argument listing call and doesn't invent filtering options that don't 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?

Specific verb (查询) plus resource (模型) and it enumerates the returned fields: model ID, install status, advanced parameter definitions. It implicitly separates itself from list_voices (voices vs models) and points at generation, though it never names the sibling tools outright.

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 – call this before generate to pick an installed model. It states when to use it but offers no exclusions or explicit alternative-tool routing.

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 must carry the full behavioral burden. It discloses that the result includes uploaded reference voices and their voiceId, but says nothing about ordering, pagination, empty results, or permissions. Listing is inherently read-only, but the description does not state that explicitly.

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 with no filler. Every word contributes to identifying the resource and the key return field.

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 no annotations, so the description should more fully explain the return shape. It mentions voiceId, which helps, but leaves the agent unsure whether the response is a simple array, an object, or includes additional metadata.

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 has zero parameters, so the baseline is 4. There are no parameters whose meaning needs to be disambiguated in the 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?

The description gives a specific verb-resource pair: '列出' (list) '已上传参考音色' (uploaded reference voices) and 'voiceId'. It distinguishes itself from upload_voice by listing uploaded items rather than uploading, though it does not explicitly contrast with list_models.

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?

Usage is only implied: an agent can infer this is how to discover available voiceId values before calling generate. There is no explicit statement of when to use this versus list_models or other siblings, and no prerequisites or exclusions are given.

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 exist, so the description carries the full burden. It does add real value by disclosing the return shape and the remote-vs-local difference between downloadPath and path, plus the default soundFont. However, it never says whether rendering is synchronous or long-running, how expensive it is, or how failures surface — material gaps for an audio-rendering tool.

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 dense paragraph with no filler sentences; every clause conveys semantics or output information. It is somewhat run-on, and the return-value note is buried mid-sentence rather than front-loaded as a separate line.

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 deeply nested input schema with no output schema and no annotations, the description covers the score model thoroughly and explains the return payload. What is missing is operational context — sync versus async behavior, and how this tool relates to the generation siblings — which leaves a small but real 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 goes well beyond the schema: it explains units and conventions (bar/beat 1-based, pitch as MIDI note number, length in beats), what program means (GM instrument number) versus drums, and what role does (selects default level) with its enumerated values. It also lists the installed soundFont IDs and the default, none of which appear 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?

Opens with a specific verb+resource+output: rendering an arranged score into a mixed-down WAV, and names exactly what comes back (id, duration, audio location). This is clearly distinguishable from siblings like generate/submit_generation/get_generation, which operate on a different pipeline.

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?

Usage is only implied by the object shape: the caller must supply a score with tempo, timeSignature and tracks. There is no explicit statement of when to pick render_score over generate or submit_generation, and no prerequisites or exclusions are given.

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 at all, the description carries the full burden, yet it says nothing about behavior: whether the call blocks, whether it returns progress percentages or queue positions, or whether it has rate/latency considerations. It only restates the read intent implied by '查看'.

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 short sentence with no filler, front-loading the resource being inspected. It is efficient but so terse that it borders on under-specification rather than exemplary conciseness.

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 tool is a zero-parameter read with no output schema, so the description is the only place to convey what come back (engine health? job progress? queue depth?). It gestures at that but does not enumerate the returned fields, leaving an agent to guess at the payload.

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 closed (additionalProperties: false), so there is no parameter semantics for the description to explain. Baseline of 4 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 ('查看'/view) and two resources: the inference engine and the current task status. An agent can distinguish it from sibling generation/voice tools. However, 'current task status' is not qualified (which task, whose task), so scope stays slightly generic.

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?

No indication of when to call this versus siblings like get_generation (which also exposes task state) or how often to poll it. The purpose is self-evident enough that an agent can infer a diagnostic use, but nothing is stated explicitly.

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, and it discloses the important traits: async submission, an immediate status return, and idempotency (same requestId plus same params will not duplicate generation). It does not cover failure modes after submission or what the immediate status payload contains, so it is strong but not complete.

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 short clauses, front-loaded with the async submit behavior and the return semantics. The idempotency note and follow-up routing each earn their place; only the trailing 'prefer this tool' sentence is slightly tacked on rather than integrated.

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, so the description correctly explains what comes back (immediate task status) and how to get the final audio. The gap is the opaque `settings` object, which an agent may need to populate but gets no guidance on here or in the 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?

Schema description coverage is 0%, so the description must compensate. It does add genuine meaning for `requestId` (client-generated, 32-char hex, idempotency key), but `text` and especially the nested `settings` object (additionalProperties: true) remain undocumented in both schema and 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 ('提交异步语音生成，立即返回任务状态') and makes the async/non-blocking nature explicit. This clearly differentiates it from the synchronous sibling `generate` and from the polling sibling `get_generation`, so an agent can select it 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?

Gives a clear usage rule: prefer this tool to avoid long-connection timeouts, and follow up with `get_generation` to poll and retrieve the audio. The comparison to the `generate` sibling is implied by 'avoid long-connection timeouts' rather than named outright, so it falls just short of fully explicit when/when-not 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 at all, the description carries the full burden; it does disclose the return value (voiceId), automatic format conversion, and size/duration caps — solid for an import tool. It omits whether the upload persists permanently, what permissions are needed, what happens on failure (e.g. audio too long), and whether name is required for later reference.

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 dense sentence that front-loads purpose, then return value, then accepted inputs, then limits — every clause carries information. It is slightly run-on with multiple parentheticals, but there is 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?

For a zero-required-parameter mutation tool with no annotations and no output schema, the description is adequate but leaves gaps: the role of the optional 'name' parameter and its default behavior, failure modes, and whether repeated uploads create new voices are all unstated.

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% so the baseline is 3, but the description adds genuine value the schema lacks: it states that path and audio are alternatives (the schema marks neither required and has no oneOf), which prevents an agent from omitting both. It also reiterates the limits applying to the audio payload, which the schema does not encode.

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 ('导入参考音频') and states the return value ('返回 voiceId'), which is more than most import tools offer. It is clearly distinguishable from siblings like list_voices, generate, or render_score, though it does not explicitly name 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?

It gives the two input modes (path or Base64 audio) and hard limits (20 MB, 1–60 s), which is useful operational guidance. However, it never says when to prefer this tool over alternatives, nor any prerequisites such as auth, quota, or whether an existing voice with the same name conflicts.

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