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

Annotations declare non-readonly, non-destructive, closed-world, so safety is partly covered; the description adds real value by clarifying the narrow blast radius — credentials survive and paid tasks are untouched. It still doesn't state what happens to the login_id afterward or the response shape.

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 tight sentences with the action and the trigger front-loaded, followed by the exclusion list. No filler, every clause carries 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?

Boundary conditions and trigger are well covered, but for a tool whose only argument is an undocumented UUID and which has no output schema, the description leaves the caller guessing how to obtain or format login_id. Adequate, not complete.

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?

One required parameter (login_id, a UUID) with 0% schema description coverage, and the description never explains it. The corpus of the description implies the id comes from start_login, but an agent must infer this rather than read it, so the description does not compensate for the schema 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?

Specific verb+resource ('Cancel the current start_login attempt') that names the sibling tool it operates on, so an agent can immediately distinguish it from start_login and wait_for_login. The negation clause further pins its boundaries.

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?

Explicit trigger condition ('only when the user asks to cancel or stop') plus four explicit exclusions (does not remove saved credentials, undo completed login, log out the website, or cancel paid tasks). This is exactly the when/when-not guidance the dimension asks for.

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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, and the description usefully explains why this is a non-read-only operation: it persists a quote with a 10-minute TTL. It also clarifies the non-destructive boundary ('Does not submit generation'). No auth requirements or rate limits are mentioned, but the TTL and the write-but-safe framing add real context beyond the 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?

Front-loaded with the core purpose and effects, followed by the model-resolution instruction and the boundary statement. Four tight sentences, though the model-selection guidance repeats the model_type theme across two sentences and could be 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?

For a 7-parameter tool with no output schema, the description covers the critical workflow: where model_type comes from, reference limits, quote TTL, prompt binding, and that it does not generate. What the estimate returns is unexplained, but no output schema exists to lean on, so that gap is the main one.

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 57%, and the description compensates meaningfully: it tells the agent to source model_type from list_image_models rather than guess, to derive reference limits from the catalog, and that the quote is bound to the exact prompt. It does not address number, quality, aspect_ratio, or image_quality semantics, which the schema only partially documents.

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 ('Estimate image credits') plus the key side effect ('save a 10-minute quote bound to the exact prompt'), and explicitly distinguishes itself from its generation sibling ('Does not submit generation'). An agent can tell this apart from generate_image and estimate_music_cost/estimate_video_cost 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 concrete conditional: 'Unless the user specified a model, pass default_model_type from list_image_models,' naming the sibling tool to consult. It also directs the agent to take the model's operation and reference limits from that catalog. It stops short of explicitly naming generate_image as the follow-up when the user actually wants to submit, leaving that 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds real value beyond them: it discloses that the call persists a saved quote ('Save a 10-minute music quote'), what the response contains ('alternative entitlement costs for internal budgets'), and a display constraint on the returned data. This is meaningful behavioral context, not a restatement.

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?

Three dense sentences, each carrying a distinct instruction (save semantics, model defaulting, output filtering), with the core action front-loaded. No filler, though 'internal budgets' and 'alternative-branch wording' are terse enough to require inference.

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 does explain the return shape ('display.estimated_costs', universal vs specialized credits) and that it does not generate. However, it leaves most of the six parameters undocumented, which is a gap for a tool with such low schema coverage.

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 only 17% – just mv is documented. The description addresses mv ('pass default_mv from list_music_models') but leaves style, title, action, lyrics, and instrumental entirely unexplained in both schema and description. With low coverage the description should compensate, and it largely does not.

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: 'Save a 10-minute music quote bound to exact input.' The closing 'Does not generate' disambiguates it from the generate_music sibling, though no sibling is named explicitly and the 'estimate vs save' framing is slightly muddled by the tool name.

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 routing guidance: 'Unless the user specified a model, pass default_mv from list_music_models' and 'Does not generate' implies when to use generate_music instead. It also constrains output display (only universal credits). No explicit when-not conditions beyond the generation note.

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=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a mutating but non-destructive open-world operation. The description adds that it saves an STS quote and does not synthesize, but provides no auth requirements, rate limits, or other behavioral details beyond the 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?

The description is short but poorly structured, with display-layer instructions such as 'Show only display.estimated_costs' that are unlikely to help an agent invoke the tool. The purpose sentence is not clearly front-loaded, and the final 'Does not synthesize' feels tacked on.

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 cost-estimation tool with five parameters, low schema coverage, and no output schema, the description is incomplete. It does not explain what the tool returns, how costs are calculated, or how the parameters affect the estimate, leaving major gaps for an agent.

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 only 20%; only voice_id has a schema description, while speech_asset_id, stability, similarity, and exaggeration are undocumented. The description does not compensate by explaining any of these parameters, mentioning only vague concepts like 'selected entitlement' and 'billable characters/seconds' without mapping them to inputs.

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 says it saves an STS quote via backend preview and does not synthesize, which gives a rough sense of an STS cost/preview tool. However, the verb 'Save' conflicts with the tool name 'estimate_sts_cost' and leaves the core purpose ambiguous. It does distinguish from generate_sts but does not clearly state it estimates costs.

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 positive guidance on when to use this tool versus estimate_tts_cost or other estimation siblings. The only usage hint is the negative 'Does not synthesize,' which excludes generate_sts but does not tell the agent when this tool is appropriate.

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 adds real behavioral context beyond annotations: final settlement happens in the synthesis backend, entitlement/account multipliers are applied via existing APIs, and the displayed number is display.estimated_costs. This is valuable non-obvious detail for a cost estimator. Note the description implies a read-style/local computation while readOnlyHint=false suggests otherwise, but the claim is not explicit enough to call a contradiction.

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?

Purpose and the no-synthesis caveat are reasonably front-loaded, but the middle is dense jargon about raw costs, entitlements and display fields ("Raw costs retain the selected entitlement for budgets; do not show billable characters/seconds as the price") that reads like internal implementation notes rather than agent-facing guidance.

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 12-parameter, no-output-schema tool with sparse annotations, the description covers the cost/settlement behavior but leaves the bulk of the parameters unexplained and gives no expected return shape guidance. It is adequate on the estimating semantics but incomplete on inputs.

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 8% (just voice_id), and 12 parameters are otherwise undocumented in the schema. The description compensates barely – it hints that text may contain SSML ("backend text/SSML counting rules") but explains none of pitch, speed, style, stability, emotion_name, etc. The agent is left to infer parameter meaning from names and ranges alone.

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 opening verb+resource ("Estimate TTS") is specific and the closing "Does not synthesize" cleanly separates it from the sibling generate_tts. However, the middle sentences about counting rules and display fields dilute the core message and make the primary purpose slightly harder to extract on first read.

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?

"Does not synthesize" implies this is the pre-flight estimate path versus generate_tts, which is useful context. But it never explicitly says when to call this instead of generate_tts, nor mentions prerequisites, so the routing guidance 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?

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds real context beyond them: the call persists a quote ("Save"), returns alternative entitlement costs, and dictates display filtering. It does not contradict the annotations, though it never states persistence duration or whether saved quotes can be reused.

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 purpose is front-loaded and the text is short, but the second half is dense agent-facing display policy ("show only universal credits...") that reads as an output-formatting instruction rather than tool selection guidance. "10-minute" is an unexplained qualifier that adds noise.

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 13-parameter, 62%-coverage tool with no output schema, the description leaves many parameters and the returned cost structure only loosely described (a single reference to display.estimated_costs). It is adequate but does not fully close the gaps left by the missing output schema and partial parameter docs.

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 62%, so some parameters (notably the bare model_type) are undocumented in the schema. The description compensates only partially by naming default_model_type as the source, and leaves content/duration/mode semantics to the schema. Marginal value over the structured fields.

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 action (Save a video quote) and explicitly rules out generation ("Does not generate"), which separates it from siblings like generate_video. The odd "10-minute" qualifier and the term "quote" versus the tool name "estimate_video_cost" leave slight ambiguity about what exactly is being saved, but the core purpose is discernible.

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 one concrete prerequisite ("Unless the user specified a model, pass default_model_type from list_video_models") and a negative boundary (does not generate). However, it never says when to prefer this over estimate_image_cost / estimate_music_cost, nor does it state when an estimate is required before generate_video, leaving usage largely 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?

Annotations already cover readOnly=false, idempotent=true and openWorld=true, yet the description goes further by disclosing that the call consumes account credits, that identical retries return the saved task, and that uncertain submissions are never auto-retried. That is genuinely additive behavioral context beyond the hints.

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?

Three dense sentences with the action and its cost front-loaded, followed by requirements and retry semantics. Every sentence carries information, though the phrasing is slightly compressed and could clarify what the retry guarantee applies to.

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 credit-consuming, non-idempotent-by-naive-reading mutation with no output schema, the description covers prerequisites, cost, and idempotency semantics. It omits what is returned (e.g. a task handle) and how to check progress, which keeps it from being fully complete.

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 only 33% (only request_id is documented). The description partially compensates by characterizing quote_id as a 'valid quote', request_id as 'stable', and max_credits as a 'maximum estimated credit budget', but it adds no format, range, or sourcing detail for quote_id and max_credits.

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 ('Submit a quoted image request') and adds the distinctive qualifier 'quoted', which signals the estimate-then-generate flow. It does not name the relevant siblings (estimate_image_cost, get_image_task), so an agent still has to infer the pipeline, but the core action is unambiguous.

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 a prerequisite ('Requires a valid quote') which steers the agent toward an estimate step, and it flags retry behavior. However, it never names the alternatives or routing (e.g. estimate_image_cost to obtain the quote, get_image_task to poll), so usage is only implied rather than explicit.

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 the write/idempotent/non-destructive profile, and the description adds genuinely new context: budgets are 'local quote checks, not backend hard caps' and request_ids must be reused only for retries of the same submission. This is useful behavior beyond the structured hints, though it doesn't address auth specifics or failure modes.

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, front-loaded sentences with no filler; the primary action leads and the constraints follow. 'Requires paid and business switches' is slightly cryptic but still earns its place as a prerequisite.

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 mutation tool with a nested budget object and no output schema, the description omits what a submission returns (presumably a task handle polled via get_generation_task) and how quotes are obtained. Adequate but leaves the agent guessing at the post-submission flow.

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 33%, so the description must compensate but only partially does: request_id is described as stable and quote_id is implied to come from a prior quote. The nested budget object's fields (credits/video_units/music_credits) are gestured at by 'budgets for every quoted resource' but not enumerated or explained.

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 ('Submit one quoted music generation') that cleanly separates it from sibling read/estimate tools like estimate_music_cost and list_music_models. An agent can identify the action 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?

Gives prerequisites ('Requires paid and business switches, a stable request_id') and one explicit when-not rule ('Never automatically retry uncertain submission'). However it never names the alternative sibling (estimate_music_cost) that produces the quote_id it consumes, so the surrounding workflow 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, openWorldHint=true), and the description adds substantive behavior beyond them: the call blocks until audio is ready, timeout/cancellation may leave backend synthesis running, unknown submissions are never retried, and budget is drawn from credits or characters. These are exactly the traits an agent needs before invoking a blocking paid operation.

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 the core action and execution mode, then workflow, then requirements, then failure semantics. Information-dense but every sentence carries operational value; slightly packed for a single paragraph but 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?

With no output schema, the description does the work of describing the return (completed result with model and available voice name, plus a task_handle) and the follow-up step. Roles are clarified ('Label this as the converted result, not the source audio') and failure behavior is covered. The only gap is the unexplained quote_id and the low schema coverage around budget semantics.

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 33%: only request_id is documented in the schema. The description compensates partially by mapping budget to 'credits or characters' and describing request_id as stable, but quote_id is never explained (its provenance from estimate_sts_cost or the generation plan flow is left implicit). Adequate but with a real gap on a required parameter.

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 (Generate) and resource (STS) and immediately pins the execution mode: 'this call waits for audio and returns the completed result.' It also differentiates itself from the async pattern used by sibling tools by stating 'No extra get_generation_task polling is required.' An agent can identify this as the synchronous speech-to-speech generator 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?

Gives clear post-call routing ('call preview_audio_task with the returned task_handle'), preconditions ('Requires a quote, stable request_id and budget'), and an explicit negative ('No extra get_generation_task polling'). It lacks an explicit when-not-to-use or a named alternative (e.g., an async path), so it stops short of a 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 cover safety (readOnly=false, destructive=false, idempotent=true, openWorld=true), but the description adds behavior they cannot express: synchronous blocking semantics, the failure mode that 'Timeout or cancellation may leave backend synthesis running', and that 'unknown submissions are never retried'. The request_id retry guidance is consistent with idempotentHint=true.

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 the core action and return contract, and nearly every sentence carries operational information. It is dense to the point of being run-on, and the card-rendering detail ('The card uses article_title and labels this as synthesized speech') is presentation trivia that slightly dilutes the guidance.

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 steps in to describe the return payload (task_handle, model, voice name, original audio link) and the required follow-up call. For a 3-required-param synchronous generator, an agent has everything needed to call it, handle success, and reason about timeouts.

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 33%, so the description must compensate, and it does map all three required inputs (quote, stable request_id, budget) and clarifies the budget is 'for the selected credits or characters'. It stops short of saying where the quote comes from (e.g. estimate_tts_cost) or how budget limits are interpreted, so it is good but not fully compensating.

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 ('Generate TTS synchronously') and immediately states the execution model — it waits and returns the completed result with model and voice name. This distinguishes it from async siblings like generate_image/generate_music that require get_generation_task polling, and from generate_sts which is a different conversion.

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 explicit routing: 'No extra get_generation_task polling is required' rules out the alternative path, and 'After success call preview_audio_task with the returned task_handle' names the exact follow-up tool and argument. Prerequisites are also stated ('Requires a quote, stable request_id and budget').

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 real context beyond the annotations: the paid/business switch requirement, the clarification that budgets are local quote checks rather than backend hard caps, and an explicit retry policy. This goes meaningfully further than the provided hints (idempotentHint, destructiveHint) and helps an agent avoid unsafe retries.

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?

Three tight sentences, front-loaded with the core action, then prerequisites, then caveats. Dense but each clause carries information; the telegraphic phrasing ('paid and business switches') is slightly terse but not wasteful.

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 mutation tool with no output schema, the description covers prerequisites and retry safety but omits what a successful submission returns (e.g., a task id to poll via get_video_task/preview_video_task) and how to satisfy or verify the required 'switches'. These gaps matter given the async-looking sibling set.

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 only 33% (only request_id is documented). The description partially compensates by explaining that request_id must be stable and that budget applies 'for every quoted resource' and acts as a local quote check, but it says nothing about quote_id's origin or how the nested credits/video_units/music_credits fields are interpreted.

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 ('Submit one quoted video generation') and the word 'quoted' distinguishes it from the sibling estimate_video_cost, implying a quote must already exist. It does not explicitly name sibling alternatives, but the action and domain are unambiguous.

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 prerequisites (paid/business switches, quote_id, request_id, budgets) and a retry rule ('Never automatically retry uncertain submission'), which is useful operational guidance. However, it never states when to prefer this over estimate_video_cost or preview_video_task, nor the quote-then-submit workflow, so the routing 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?

Annotations declare readOnlyHint=false and openWorldHint=true, and the description usefully reconciles the non-read-only hint by disclosing that membership queries may initialize first-use entitlements — a side effect beyond what the annotations state. It does not quantify the side effect or describe the response, but this is genuine added 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?

Two short sentences, front-loaded with the primary action and followed by the side-effect caveat. No filler sentences and nothing 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?

For a zero-parameter tool with no output schema, annotations covering the safety profile, and a stated side effect, the description is largely sufficient. The only gap is that 'tp_all' entitlements are left unexplained and the returned shape is not characterized, though no output schema exists to lean on.

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; baseline for a parameterless tool is 4. Schema coverage is 100% but vacuous here.

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 clear verb+resource ('Get ... account ... entitlements'), so an agent knows this returns entitlement data. However, it never distinguishes this tool from the sibling per-service entitlement tools (get_music_entitlements, get_video_entitlements, get_speech_entitlements), and the term 'tp_all' is opaque jargon that adds no clarity.

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 explicit when-to-use guidance and no routing between this general balance tool and the service-specific entitlement siblings. The note that queries 'may initialize first-use entitlements' hints at a precondition, but it is stated as a behavioral caveat rather than 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?

'Does not call a backend' adds a concrete behavioral fact (no network round-trip, cheap to call), which is useful. However, openWorldHint=false and readOnlyHint=true in the annotations already signal a non-mutating, non-external operation, so the added value is modest rather than substantial.

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 no filler; the scope of what is inspected comes first and the operational caveat second. Every clause 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 zero-parameter, read-only inspection tool this is nearly complete, and the description names the inspected dimensions. With no output schema present, it could say a bit more about what a 'readiness' or 'approved route' result looks like, but the gap is small.

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 and the baseline of 4 applies. No parameter information is needed or missing.

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 (Inspect) and a clearly scoped resource (implementation readiness and approved route availability) and enumerates the modalities covered. It does not, however, differentiate itself from nearby siblings like get_service_status or the per-modality get_*_entitlements tools, leaving the agent to infer the boundary.

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: 'inspect readiness and approved route availability' suggests a pre-flight check before calling generate_* tools. There is no explicit statement of when to prefer this over get_service_status or get_music_entitlements, nor any exclusion.

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 declare readOnly/openWorld/non-destructive, and the description adds substantial behavior beyond that: cached:true responses with remaining wait and no backend request, no retry on uncertain submissions, reconciliation via website history, and a rejection of arbitrary backend IDs. This is genuinely useful context an agent could not infer from the 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?

It is a dense wall of prose mixing polling semantics, UI/presentation instructions, and delivery formatting, with 'Do not reopen the same card' repeated for both audio and video. The core read-a-task purpose is buried behind downstream workflow rules rather than front-loaded, so much of the text does not earn its place in a getter's description.

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 states that matter (completed/failed), the result shape (artifacts[].url, model, voice, consumption with credit type, duration), and the polling contract. The remaining gap is that it never states whether image-generation tasks are also served by this tool versus get_image_task.

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 single parameter has 0% schema description coverage (schema supplies only format/pattern), so the description carries the meaning: the handle is account-scoped, was created by this MCP, and arbitrary backend IDs are never accepted. That is exactly the semantic layer the schema lacks, though it does not describe handle lifetime or reuse.

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 concrete verb+resource: read an account-scoped task_handle created by this MCP, and scopes it to music/video/speech task families. It never explicitly distinguishes get_generation_task from siblings like get_image_task or get_music_entitlements-family tools, leaving the agent to guess whether image tasks route here or elsewhere.

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?

Strong operational guidance: wait poll_after_seconds (~20s) between queries, stop polling on completed/failed, concurrent calls return cached state, and route to preview_audio_task/preview_video_task once at completion. It lacks explicit when-not-to-use-this-tool guidance (e.g. which task types belong to get_image_task), so it stops short of full routing clarity.

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 the safety profile (readOnly, non-destructive), and the description adds substantial behavior beyond them: caching semantics with cached:true and remaining wait, no backend request on early/concurrent calls, no store lock held during network requests, independence of different tasks, and the fact that no generation is submitted or charged. These are non-obvious traits that materially change how an agent should poll.

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 polling cadence, then return values, then a scope disclaimer. Every sentence carries information, though the middle clauses about store locks and concurrent calls are dense and read more like implementation notes than agent-facing guidance, slightly inflating the length.

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 compensates by stating what is returned (result URLs and image resource links). Combined with polling cadence, stop conditions, cache behavior, and the no-charge disclaimer, 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%, so both request_id and refresh_result are already documented in the schema, including reuse-for-retries and the expired-link recovery behavior. The description references request_id only indirectly via polling semantics and adds no field-level meaning beyond the schema, making the baseline 3 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: queries a task created by TopMediAi-MCP via request_id, and explicitly disclaims submitting or charging. It is clear what the tool does, but it never differentiates itself from the sibling get_generation_task, leaving the agent to infer the image-specific scope from the tool name and schema text ('owned image task').

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 explicit operational guidance: wait poll_after_seconds (normally 20s) before re-querying, stop normal polling on completed or failed, and use preview_image_task with clickable original links once images are available. It also states when NOT to expect value from an early call (cached:true, no backend request), which is exactly the routing context an agent needs.

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 cover safety (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description adds meaningful context that supports them: the backend may initialize first-use entitlements, which explains why a 'get' is not purely read-only. It also discloses that music_credits are internal settlement data that must not be surfaced, which is genuine behavioral guidance beyond the 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?

Three tight sentences with the purpose front-loaded and the most consequential constraint ('must not be shown even when nonzero') given emphasis. Every sentence carries a distinct instruction, though the display rule borders on presentation policy rather than tool semantics.

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 tool with no output schema, the description supplies purpose, a data-handling rule, and a side-effect caveat. It could go slightly further by hinting at what a successful response contains (e.g., universal credit fields), but it is largely sufficient.

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 4-point baseline applies. There is nothing for the description to add, and it correctly does not invent parameter 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+resource ('Query music entitlements'), which cleanly distinguishes it from the parallel get_video_entitlements and get_speech_entitlements siblings by resource domain. It lacks any explicit differentiation text, but the resource name carries the distinction.

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 tool versus the sibling entitlement tools, nor any stated preconditions or ordering (e.g., before generate_music or estimate_music_cost). The display instructions govern result presentation rather than tool selection.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful non-obvious behavior: it does not perform a network login, does not reveal credentials, and it reports a refreshed credential source rather than raw secrets — all beyond what the annotations state.

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?

Three tight sentences: the first front-loads what is reported, the second warns about token validity, the third bounds the side effects. No filler, though the first sentence is a slightly dense comma-list of nouns.

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 diagnostic with no output schema, the description adequately enumerates the fields an agent will get back and explicitly bounds side effects. It does not describe the shape of the response or error states, but for a tool this simple that is a minor 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, so the baseline is 4; there is nothing for the description to disambiguate. No argument syntax is needed and none is missing.

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 concrete verb (Check) and enumerates the specific signals returned: environment, credential source, login guidance, and generation-enabled state. That is clearly distinguishable from sibling actions like start_login or generate_image, though it never names the adjacent diagnostic siblings (get_balance, get_generation_capabilities) it might be confused with.

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. The caution that 'a configured token is not proof of a valid backend login' hints this should be run to verify login state before generating, and the note that it does not perform a network login implicitly routes real login work to start_login, but no alternative is named and no when-not condition is stated outright.

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 declare openWorldHint=true and destructiveHint=false, so safety is mostly covered, and the description usefully clarifies that this is a read of existing membership APIs (i.e. a lookup, not a generation or mutation) and that no per-voice data is returned. It does not disclose auth/membership prerequisites, caching or freshness of the entitlement values, or what the response shape looks like, which matters since there is no output schema. The readOnlyHint=false sits in mild tension with the 'Read' wording, though it reads as an unset default rather than an affirmative claim.

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, and the primary answer (what entitlements are read) is front-loaded ahead of the scope caveat. Every clause carries information an agent can act on.

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 lookup with no output schema and thin annotations, the description conveys the returned data at a high level and explicitly rules out voice-level figures, which prevents a foreseeable misuse. It could say slightly more about when in a workflow to call it, but nothing essential is missing 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?

The tool takes zero parameters and the schema is a closed empty object, so there is nothing for the description to disambiguate. Baseline of 4 applies; no parameter-level detail is needed or missing.

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 (Read) plus a precise resource list — speech characters, universal credits, and full TTS generation permission — pulled from membership APIs. It is immediately distinguishable from siblings like get_music_entitlements and get_video_entitlements by the 'speech' scope, and the second sentence draws the boundary around what this tool does not cover.

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 effectively routes the agent: voice-specific characters and multipliers are not answered here and are instead resolved during a TTS estimate, which points at estimate_tts_cost. It stops short of saying when to call this (e.g. before generate_tts) or how it relates to get_balance/get_generation_capabilities, so it is clear but not exhaustive.

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 declare readOnlyHint=false and destructiveHint=false but give no reason; the description supplies the missing context that the call 'may initialize first-use entitlements,' i.e. an implicit write side effect. It also discloses the important output-filtering rule about legacy video_units being internal settlement data, which is non-obvious behavioral context beyond the 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?

Three tight sentences, zero filler: purpose first, then the display constraint, then the initialization side effect. The most decision-relevant constraint (what may not be shown) is front-loaded ahead of the softer side-effect note.

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 parameters and no output schema, the description carries the return-value burden and only partly does so: it names two concepts (universal credits, legacy video_units) but not the actual field names or shape of the response, so an agent still cannot know exactly what to render. Adequate for a simple zero-arg query, but not complete.

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 and the baseline is 4. The description correctly does not invent or discuss 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 states a specific verb+resource: 'Query video entitlements through the membership backend,' which an agent can distinguish from the sibling entitlement tools (music, speech) by the video resource. It does not explicitly name the siblings, so it falls short of full sibling differentiation, but the purpose is unambiguous.

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: the description never says when to call this versus estimate_video_cost, generate_video, or the other entitlement tools. The only conditional language ('legacy video_units... must not be shown') is output-handling policy, not tool-selection 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, destructiveHint, and openWorldHint. The description adds useful behavioral context beyond those: it is session-scoped (voice must have been returned by list_voices in this session) and it explicitly does not trigger TTS. However, it does not cover rate limits or error 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?

Two sentences, front-loaded with the core action and scope. Every clause adds information: what metadata, where the ID comes from, and what the tool does not do.

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 read tool with no output schema, the description covers purpose, usage context, and the type of metadata returned ('accent and emotion'). It lacks detail on what happens if the voice is not found or not public, but the annotations and schema cover most other needs.

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 provides provenance for the voice_id parameter (it comes from list_voices), which is helpful, but does not describe the expected format or any constraints beyond what the schema's pattern already imposes.

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 ('Read'), resource ('accent and emotion metadata for a public voice'), and scope ('previously returned by list_voices in this session'). It also explicitly distinguishes itself from TTS generation, making it easy to identify among siblings.

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 clearly states when to use it: after list_voices, on a public voice returned in the current session. It also provides a when-not condition ('Does not authorize or perform TTS'), but does not name any alternative tools for related lookups.

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 establish readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: pricing is live per row, missing prices never suppress a model from the listing, and default_model_type is the fallback selector. It does not discuss pagination or refresh behavior, keeping it just shy of a 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?

Three sentences, all load-bearing, with the core purpose front-loaded before the fallback and quoting caveats. The middle sentences are dense but each conveys a distinct rule, so nothing reads as 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?

With no output schema, the description carries the burden of describing the return and does so usefully: a model catalog, per-model capabilities, model.pricing rows, and an independent pricing_status, plus default_model_type. An agent knows enough to consume and act on the result, though the exact shape of the capabilities object remains unspecified.

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; there is no parameter surface the description needs to disambiguate. The description correctly adds no invented parameter 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?

The description names a specific verb and resource ('List the complete Web image model catalog and per-model capabilities') and enumerates what the listing contains, including price rows and pricing_status. This distinguishes it cleanly from the parallel list_video_models, list_music_models, and list_tts_models siblings without needing to 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 conditional workflow guidance: when no model is specified, fall back to the returned default_model_type, and 'use an exact quote before generation' which implicitly routes the agent toward the cost-estimation step. It stops short of explicitly naming estimate_image_cost as the next call or stating when not to use this tool, so it is clear context rather than a full when/when-not/alternative matrix.

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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: pricing_status is independent and 'prices never filter model visibility,' which tells the agent to expect models with non-available pricing to still appear, plus the default_mv behavior. It doesn't cover pagination or refresh/rate-limit 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?

Three short sentences, front-loaded with the core action and scoping rule. The hardcoded 'v6-pro, v6-wild-pro, v6-mini' list earns its place as a routing hint but is the kind of version-specific detail that goes stale and could have been summarized.

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 it does cover the key fields (capabilities, pricing_status, default_mv, mv values). It leaves the shape of 'capabilities' unspecified, which is a modest gap for a zero-parameter catalog 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter discussion, and the embedded 'Current mv values' enumeration is a value-domain hint rather than a parameter specification.

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 ('List the complete current Web music catalog') and names the payload contents (capabilities, pricing_status). The 'music' qualifier plus the mv enumeration cleanly separates it from sibling listers like list_image_models, list_tts_models, and list_video_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?

Gives explicit downstream guidance: 'When the user has not specified a model, use the returned default_mv.' It also implies why you'd call this tool (to discover models and their pricing before estimating/generating). It stops short of naming an alternative tool or an explicit when-not-to-call 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds workflow context (voice selection path, synchronous generation), but the synchronous-generation note actually describes generate_sts rather than this listing tool, and nothing is said about the shape or size of the returned list.

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?

Three short sentences with no padding, but the final sentence about synchronous generation and direct audio return is about a different tool and reads as drift rather than front-loaded relevance. The core purpose sentence is correctly placed first.

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 list tool with no output schema, the description should convey what the returned catalog looks like. It names "channels and parameters" but does not characterize the entries, leaving the agent to discover the return structure on its own.

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 and the schema is trivially complete. 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?

The description opens with a specific verb and resource ("List STS channels and parameters"), which is clearly distinct from sibling list_tts_models and list_video_models. It stops short of explicitly differentiating STS from those siblings, but the domain term does the work.

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 a useful downstream step ("Select a public voice_id using list_voices with operation=sts") but never states when to call this tool versus list_tts_models or list_voices directly. Usage is implied by the workflow context rather than stated with exclusions.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that generation is synchronous and returns audio directly, but that is about generate_tts, not about this listing call's own behavior (caching, latency, return shape), so the added value is modest.

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?

Three short sentences, front-loaded with the purpose and zero wasted words. The closing sentence about synchronous generation is slightly off-topic for a listing tool but earns its place as downstream workflow 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 zero-parameter, read-only listing tool with no output schema, the description is sufficient to pick and call it correctly. It could say more about the shape of the returned channel/parameter data, but the complexity is low enough that this is a minor 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, so there is nothing for the description to document; baseline is 4. 'Channels and parameters' refers to returned content rather than inputs, so no input semantics are needed or missing.

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 ('List TTS channels and parameters'), clarifying what the 'models' in the name actually are, and the TTS qualifier distinguishes it from sibling list_music_models / list_video_models / list_sts_models. It stops short of explicitly naming those siblings as the thing it is not.

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 clear workflow context by pointing to list_voices with operation=tts as the next step to obtain a voice_id, which implies this tool is used when assembling a TTS generation request. It does not state explicit exclusions versus other list_* tools, but the sequence guidance is concrete.

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 readOnlyHint/destructiveHint/openWorldHint already covering the safety profile, the description adds genuine operational context: pricing_status is live and independent of visibility ('prices never filter model visibility'), a default_model_type is returned, and variable-duration models require a backend duration protocol ID plus real_duration from capabilities. This is real behavior beyond the annotations, though the duration-protocol mechanics remain cryptic.

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 first sentence is front-loaded and earns its place, but the pricing_status independence claim and the duration-protocol sentence are dense and partly redundant, and the closing sentence is cryptic. The block reads as packed operational notes rather than a cleanly prioritized description.

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 usefully names what comes back (capabilities, live pricing_status, default_model_type), which is exactly what an agent needs to act on the result. It is close to complete for a read-only catalog tool, losing a point only for the unexplained duration-protocol requirement.

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 carry parameter meaning. It enumerates the operation values (mostly duplicating the enum) and names the default, and gives a thin gloss for generate_audio ('Select generate_audio to match the quote'). That is a partial compensation, not a full one, since the non-obvious 'duration protocol ID' concept is referenced but never tied to a parameter.

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 opening clause states a specific verb+resource ('List the complete current Web video catalog') plus the payload (capabilities and pricing_status), clearly distinguishing it from list_image_models / list_music_models / list_tts_models. The remaining sentences drift into selection instructions rather than purpose, but the core intent is unambiguous.

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 conditional guidance for the operation parameter ('Select text_to_video (default), image_to_video...') and a rule for model defaulting ('When the user has not specified a model, use the returned default_model_type'). However, it never says when to call this versus the adjacent catalog/costing tools (estimate_video_cost, generate_video, preview_video_task), so routing against siblings 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?

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely new behavioral context: results are 'public voices' only and the tool 'Uses bounded local pagination,' which is not derivable from the annotations or schema.

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?

Three compact sentences with the core purpose front-loaded, followed by pagination and workflow notes. Minimal waste, though the trailing sentence about obtaining a quote drifts slightly from the tool's own scope.

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 5 parameters at 0% schema coverage and no output schema, the description should explain what the parameters filter and what is returned. It covers only the operation mode and pagination style, leaving the agent unable to use lang, search_text, page, or page_size 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 0% across 5 parameters, so the description must compensate. It mentions only 'operation tts (default) or sts' and leaves lang, page, page_size, and search_text completely unexplained in both the schema and 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?

States a specific verb (List) and resource (public voices), and names the operation modes tts (default) and sts. It is reasonably distinguishable from siblings like list_tts_models/list_sts_models since voices are a distinct resource, though it never explicitly contrasts itself with 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?

Gives a workflow hint ('Read get_voice_detail, then obtain an exact speech quote before generation') and names a sibling, implying sequenced usage. However it gives no guidance on when to pick this over list_tts_models/list_sts_models, and no exclusions or prerequisites beyond the workflow tip.

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?

Goes well beyond the readOnly/openWorld/destructive annotations by enumerating negatives: no backend polling, no media download, no generation, no spending, no configuration changes. It also discloses the interaction detail that playback starts only on user click, 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 what is shown, then conditions, then constraints. Dense and mostly waste-free, though the final sentence about named original links for hosts without UI support is a host-rendering convention that sits slightly awkwardly in a tool description.

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 covers the return surface (separate versions, playback/seek controls, retry and original links) and the full safety profile for a read-only preview. An agent has everything needed to call it correctly once the task is complete.

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?

One parameter (task_handle) with 0% schema description coverage, so this dimension cannot lean on the schema. The description supplies context that the handle must reference an 'owned locally saved task', implying ownership and prior completion, but never states the handle format or where it comes from.

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 (Show) and resource (generated music/speech) plus the delivery mechanism (inline player) and the source constraint (owned locally saved task). It is immediately distinguishable from preview_image_task/preview_video_task and get_generation_task.

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?

"Call once when completed audio becomes available" gives an explicit trigger condition, and "Reads saved results only: no backend polling" steers the agent away from using this as a poller. It does not name the sibling that should do the waiting/polling, so it stops short of a 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description usefully adds that nothing is fetched from the backend, no credits are spent, and that host UI support is mandatory with original links required. However it does not explain what the preview card returns or the load/error/retry state semantics of those controls. With annotations carrying the safety profile, this is solid added context but not exhaustive 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?

Purpose and card contents are front-loaded in the first sentence, with sequencing and exclusions following. Every clause carries information, though the dense packing of four separate behavioral claims into the second sentence slightly reduces 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 one-parameter, read-only presentation tool with no output schema, the description covers the trigger, the exclusions, the host UI requirement and the need to provide original result links. An agent has everything it needs to decide to call it and to set expectations for the caller.

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 is a single parameter (request_id) with 100% schema description coverage, so the schema already documents its purpose, pattern and retry reuse semantics. The description adds nothing about the parameter, which is acceptable under the high-coverage baseline but earns no extra credit.

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 ('Show already generated images ... in a read-only preview card') and immediately scopes it against the obvious alternative by declaring it does not query the backend. An agent can distinguish it from get_image_task, preview_audio_task and preview_video_task without opening any 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?

'Call after get_image_task returns images' gives an explicit precondition and ordering relative to the retrieval sibling. It also lists when-not conditions (no backend query, no media download, no generation submission, no credit spend) and a host-environment prerequisite plus the obligation to supply original links.

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 readOnlyHint/destructiveHint/openWorldHint already declaring the safety profile, the description still adds substantial behavioral context: playback only on user click, reads saved results only, and an explicit negative list (no backend polling, media download, generation, spending or configuration changes). This tells the agent exactly what side effects will not occur.

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 the core purpose, then behavior, then the host-support caveat. Dense and mostly free of filler, though the enumeration of player features (seek, volume, fullscreen, retry) is borderline detail an agent does not need for tool selection.

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-param read-only preview tool with no output schema and full annotation coverage, the description covers purpose, trigger, and non-effects adequately. It does not describe what happens if the task has no completed video yet or the handle is invalid, which is the main remaining 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?

Only one parameter (task_handle) with 0% schema description coverage, so the description should compensate. It hints that the handle refers to an 'owned locally saved task', implying ownership and locality constraints, but adds no format, lookup or failure semantics beyond the schema's UUID pattern.

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: 'Show generated videos ... in an inline player', so the agent immediately knows this renders existing video output rather than fetching or generating it. It does not explicitly differentiate itself from siblings like get_generation_task or preview_audio_task/preview_image_task, which is the only thing keeping it out of the top band.

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 trigger condition ('Call once when completed video becomes available') and a deployment caveat ('Always also include named original video links for hosts without UI support'). It does not name the alternative to use when the video is not yet complete, so usage is implied rather than fully routed.

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 cover the safety profile (readOnlyHint false, destructiveHint false, openWorldHint false); the description adds substantive behavior beyond that: it deduplicates retries, shows universal credits only, flags high-price models and totals over 1000, keeps specialized entitlement costs internal, and explicitly states queries do not authorize generation or record consent. That is meaningful disclosure of output behavior and non-authorization, though the actual side effects of persisting a plan are not spelled out.

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?

Purpose is front-loaded and most sentences carry operational weight, but the single dense paragraph is jargon-heavy and overlaps with the schema descriptions of confirmation_mode and confirmed_plan_id. Some clauses (specialized entitlement costs remain internal) could be trimmed without loss.

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 return-value explanation, and it only partially discharges this by implying what it displays (universal credits, high-price models, totals >1000). For a complex planning tool consuming flow_id, steps, submitted_steps and confirmation state, the description is adequate but leaves the returned plan structure and confirmed_plan_id lifecycle somewhat implicit.

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 baseline is 3. The description reinforces semantics for confirmation_mode (latest explicit preference in this conversation, conditional default) and confirmed_plan_id (only after human approval of that exact plan), but largely restates what the schema descriptions already state. It adds little beyond the structured fields.

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: it reviews the complete current creative flow before a paid submission, using saved quotes and submitted request IDs. That distinguishes it from siblings like estimate_image_cost (pure cost lookup) and generate_image (actual execution). It lacks an explicit mention of sibling alternatives, but the scope 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?

Gives real timing guidance ('before a new paid submission') and conditions for confirmed_plan_id ('only after human approval here'), plus the confirmation-mode default rule. However, it never names which alternative tools to use instead (e.g., estimate_* vs. generate_* vs. this review step), leaving the agent to infer the position in the flow.

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 provide a coarse safety profile (non-readonly, open-world, non-destructive). The description adds meaningfully more: the returned value is an opaque login_id, the call is idempotent-ish ('Reuses an active attempt without opening another page'), and it explicitly discloses what is NOT returned ('Never returns a token or private handoff link'). That is exactly the behavioral context annotations cannot carry.

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?

Three sentences, front-loaded with the action and return value, then the reuse constraint, then the flow requirement. No filler and each sentence carries 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?

No output schema exists, so the description takes on the burden of describing the return value, which it does ('opaque login_id', and what is never returned). For a parameterless orchestration step that must be chained with wait_for_login, 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?

There are zero parameters, so the baseline is 4. The description correctly mentions the single output (login_id) but has no parameter-level detail to add, and none is needed.

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 official website login on this computer') plus the concrete artifact produced ('return an opaque login_id'). It also disambiguates from other login-flow siblings by noting that it reuses an active attempt rather than opening a new page.

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 downstream: 'call wait_for_login until saved or a terminal outcome, then verify status/balance and resume the original request.' It states both the required follow-up tool and the sequencing condition, so the agent knows how to use this in context rather than in isolation.

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 mark this as a non-readonly, non-idempotent, non-destructive open-world write. The description goes well beyond that, disclosing metadata stripping, a 5 MiB cap, login verification, the account-scoped reference_image_id, the possible side effect of a publicly retrievable OSS URL, and explicitly that an uncertain upload is never auto-retried.

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 side effects and constraints in tightly packed sentences, with no filler. Minor redundancy between the source-directory phrase in sentence one and the 'requires a configured dedicated directory' sentence keeps it from a 5.

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 correctly carries return and failure semantics (reference_image_id, no auto-retry) plus preconditions and side effects. The one real omission is disambiguation from the sibling upload_reference_media, which an agent genuinely needs before calling.

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 single parameter is fully documented in the schema (path inside TOPMEDIAI_UPLOAD_ROOT, no URLs/symlinks). The description still adds meaning by constraining accepted format (PNG/JPEG), the source directory concept, and a size limit, though it does not restate path syntax the schema already covers.

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 ('Upload a user-authorized local PNG/JPEG') and narrows scope to image-to-image or video first/last frames, which an agent can act on. However, it never distinguishes itself from the near-identical sibling upload_reference_media, so an agent faces an unresolved choice between the two.

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 states a prerequisite ('Upload requires a configured dedicated directory') and rules out an alternative action ('Does not generate or debit credits'), which implies context. But it gives no explicit when-to-use guidance and offers no routing versus upload_reference_media, leaving the primary selection decision 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing that media is re-encoded with metadata stripped, the real container and duration are validated, login is verified, and the result is an account-scoped id. It also flags that existing storage URLs may be public and that uncertain uploads must not be retried — exactly the mutation-side context annotations cannot carry.

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 sentences, all front-loaded with the core action first, then requirements, then behavior, then caveats. Dense but nearly every sentence carries non-redundant information; only mild compression of the requirement list is possible.

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 correctly names the return value (reference_media_id) and its account scoping, plus the validation performed. Little is missing for a 3-parameter upload tool, though failure modes (e.g., what error text an invalid container produces) are left implicit.

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 67%, and the description compensates by defining the accepted container types for media_type (MP4/WAV/MP3) and reinforcing the upload-root constraint on file_path. The model_type duration distinction is already in the schema, so it adds no new detail there, keeping this at a strong 4 rather than 5.

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 and resource ('Upload one user-authorized local MP4 video or WAV/MP3 audio for omni reference video generation'), naming accepted formats and the downstream purpose. This clearly separates it from upload_reference_image and upload_speech_audio without needing to open their schemas.

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?

States prerequisites (dedicated upload directory, user authorization, local FFmpeg/FFprobe) and two explicit exclusions: it does not generate or spend credits, and it should never auto-retry an uncertain upload. It stops short of naming sibling tools like upload_reference_image as the alternative path, so context is clear but alternatives are unstated.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new operational detail: 50 MiB / 300 s limits, a local FFmpeg/FFprobe dependency, and the privacy-relevant note that existing upload URLs may be public. It stops short of describing failure/error behavior or auth prerequisites.

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 clauses, front-loaded with the action and its source constraint, then limits, dependencies, side effect, and exclusions. No filler sentences; each clause carries a distinct fact.

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 upload tool with no output schema, the description supplies the return value (a local account-scoped speech_asset_id), the size/duration bounds, and the non-synthesis scope. Only the file_path semantics and failure behavior remain thin.

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% and the single file_path parameter is undocumented in the schema. The description only indirectly informs it by stating files must live under TOPMEDIAI_UPLOAD_ROOT, giving the parameter a scoping constraint but no format, extension, or path syntax guidance.

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 (upload) and resource (one externally authorized audio file) with a clear scope qualifier (from TOPMEDIAI_UPLOAD_ROOT). The resource name cleanly separates it from upload_reference_image and upload_reference_media, though it never names those siblings explicitly.

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 establishes the preconditions for use (external authorization, files sourced from TOPMEDIAI_UPLOAD_ROOT, FFmpeg/FFprobe installed) and excludes synthesis ('No synthesis or automatic retry'), but never states when to pick this over upload_reference_media or how it relates to generate_sts. Usage is implied rather than routed.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: the 25-second wait cap, the polling-loop contract, the 'waiting'/'saved' state semantics, and an explicit negative scope. It stops short of enumerating other possible states (failure, expiry) or how they surface, which keeps it at 4.

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?

Three tight sentences with zero filler, front-loaded on the wait duration and followed by the two outcome branches. Every clause carries operational instruction; nothing is repeated from the schema or annotations.

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 polling tool with no output schema, the description covers the return states it names, the control-flow response to each, and the prohibited actions. The only gap is that it does not say what to do on terminal non-success outcomes (failure/expiry), leaving an agent without a branch for those cases.

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 carry both parameters, and it only partly does. 'the start_login attempt' implies login_id comes from start_login, and 'up to 25 seconds' loosely maps to wait_seconds' default/maximum, but neither parameter is explained directly and the 1–25 range is never mentioned. Baseline 3 for a 2-param tool with no schema prose.

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 ('wait up to 25 seconds for the start_login attempt') and anchors itself to a named sibling (start_login), so an agent can distinguish it from get_service_status, get_balance and the rest of the login lifecycle 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 explicit conditional routing: on 'waiting', re-call with the same login_id and do not end the reply; on 'saved', verify via get_service_status/get_balance and resume the original request. It also states what it must NOT be used for (open a page, submit generation, retry a paid request), which is exactly the when/when-not guidance needed.

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