VerseIn

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds the non-obvious business consequence that the charged coins are not refunded, which is real value beyond structured fields. It does not describe auth requirements or rate limits, but the refund warning and platform restriction are the high-value disclosures here.

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: what it does first, the cost consequence second, the platform restriction last. Every sentence carries actionable information and nothing is 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?

Output schema exists, so return values need no explanation. The description covers purpose, cost consequence, and eligibility limits, which is nearly everything needed to call it correctly; only the provenance of task_id is left unstated.

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

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

Schema description coverage is 0% and the single parameter task_id is documented nowhere, so the description had room to compensate and does not (no guidance on where to source a task_id or its format). Because there is only one required, self-evidently named parameter, this remains minimum-viable rather than broken.

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 (stop/cancel) applied to a specific resource (a submitted task), with a scope qualifier that tasks from web/app are out of bounds. No sibling tool competes for this purpose, so nothing further is needed for differentiation, though it never explicitly contrasts with get_tasks/list_recent_tasks.

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?

"Tasks started on the web or in the app cannot be canceled here" is an explicit when-not-to-use exclusion, which is more than most definitions offer. It stops short of the positive path (how to obtain a valid task_id, e.g. via list_recent_tasks), so there is a small inference gap.

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: it discloses that the call costs real coins, that price scales with video length, that high-cost calls are gated behind a confirmation token, that unlimited-plan allowances don't apply, and that the result is async (task id, follow with get_tasks). This is exactly the billing and side-effect context destructiveHint=true alone 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-loads the core action in the first sentence and keeps the confirmation loop tight. There is mild redundancy: 'Spends the user's coins' and 'charged in VerseIn coins' repeat the same point, and the media-URL requirement is stated twice.

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

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

Given an output schema exists and the cost/confirmation mechanics are the real risk here, the description covers everything an agent needs: input format, billing model, confirmation gate, and the follow-up task-tracking step. Nothing material is left out.

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

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

Schema coverage is 100%, so video_url, speed, colormap, request_id, max_total_coins and confirmation_token are already documented in the schema. The description reinforces the confirmation_token and cost-cap interplay but adds little about speed or colormap beyond what the schema says, so baseline 3 applies.

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

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

States a concrete verb and resource — turn a video into a depth map video — with the required input format (VerseIn media URL) named up front. It is clearly a distinct transformation from siblings like reframe_video, relight_video and upscale_video, but it never explicitly draws that distinction, leaving the agent to infer it from the 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?

Explains the full call flow: if the price is above the threshold you get needs_confirmation, ask the user, then re-call with the token; it also points at estimate_cost as the source of max_coins. What's missing is explicit routing guidance (when to pick this over edit_video or generate_video), so there's clear context but no 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?

Adds substantial context beyond the annotations: the two-phase flow (create → PUT → media_url), the network requirement for direct uploads, and the fact that the chat-app path delegates to a user-driven card. These are non-obvious behavioral traits for a tool with readOnlyHint=false and no idempotency (idempotentHint=false is meaningfully reinforced by the one-shot upload semantics). Nothing here contradicts the declared 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?

Four sentences, front-loaded with the action, then the two modes, then the follow-up step. Every sentence carries decision-relevant information with no filler or repetition of schema text.

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?

Despite an output schema existing, the description covers the return contract that matters for callers (upload_url, headers, media_url) and tells the agent what to do next. For a three-parameter, non-destructive creation tool with an open-world PUT step, 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?

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining that filename and size_bytes are a paired mode switch — omitting them shows the card, supplying them means the caller does the PUT itself. This adds operative meaning about when to supply them, though it does not elaborate on the model parameter's size-limit behavior beyond what the schema says.

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 ("Upload a local image or video to VerseIn") and immediately scopes it to local files, which implicitly separates it from import_media_from_url and pick_media. It also names the two operational modes and the downstream consumer ("generation tools"), so an agent knows exactly what the tool produces.

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 guidance: chat apps call it with no filename/size_bytes to show the upload card, while agents holding the file and with network access pass filename plus exact size_bytes. The follow-up action ("PUT it to the returned upload_url with the returned headers") and next step ("Pass media_url to generation tools") are stated. It stops short of naming alternatives like import_media_from_url or pick_media for the cases this tool does not cover.

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 — coin cost tied to length, the needs_confirmation/confirmation_token round-trip with the user, an async task-id return, and a hard refusal policy for face/identity edits. However it omits the request_id idempotency guarantee documented in the schema, which sits in tension with the idempotentHint: false annotation and would have been valuable at the description level for a destructive, non-idempotent, charged 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?

Five front-loaded sentences and every one carries decision-relevant content. The coin-charging point is stated twice in slightly different words ('Spends the user's coins' and 'charged in VerseIn coins… Unlimited-plan allowances do not apply'), which is minor redundancy rather than bloat.

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 an 11-parameter, costly, asynchronous mutation with a confirmation gate, the description covers cost, gating, async follow-up, and prohibition. With an output schema present it correctly does not attempt to enumerate return fields, only the one thing the agent must act on (task id → get_tasks).

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

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

Schema coverage is 100%, so per-parameter meaning is already covered; the description still adds workflow-level semantics for the confirmation_token/max_total_coins pair (price may change between estimate and call, and the call is blocked until the user agrees) that the schema alone only implies field-by-field.

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 — edit a video from a text instruction — plus input form (a VerseIn media URL) and optional reference media. This clearly separates it from generate_video, extend_video, reframe_video and upscale_video, which operate on different intents.

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

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

Gives an explicit when-to-use (transform an existing video per a prompt), an explicit when-not-to-use (face swapping or placing a real person's identity on someone else, which is refused), and routes the agent forward to get_tasks and backward to estimate_cost/max_total_coins for pricing. Little 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 only declare readOnlyHint; the description adds substantive behavior: nothing submitted or charged, the answer carries max_coins used by confirmation/affordability checks, pricing an editing tool inspects media exactly as the tool does, requires the same generate permission, and inherits the tool's limits. This is well beyond what the annotations 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 the core action and the no-submit guarantee, then details the two calling modes and the permission/limit caveats. Dense but each sentence carries information; the closing billing notes are slightly tangential but relevant to cost interpretation.

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?

An output schema exists so return shape needn't be spelled out, yet the description still flags max_coins for editing tools, plus permission and limit behavior and the billing context. Nothing material for correct invocation 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?

With 100% schema coverage the baseline is 3, but the description adds cross-parameter routing semantics the schema cannot express: media+items versus tool+input are mutually exclusive modes, and input should be the exact arguments of the target tool. That meaningfully reduces misuse risk.

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 — price generations and editing jobs — and immediately clarifies it submits nothing, which is exactly what distinguishes it from the sibling generate_*/edit_* tools. An agent can tell what it does and what it does not do from the first sentence.

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 rules: pass media+items for generate_image/generate_video, or tool+input to price one of the eight named editing tools 'with the same arguments you would call it with.' It also frames the use case (compare against balance, no charge). No explicit when-not-to-use exclusions, so not 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?

Goes well beyond the annotations: it discloses that the call spends the user's coins, that calls above a threshold return needs_confirmation, and that unlimited-plan allowances explicitly do not apply. That price-gating and billing context is exactly what an agent needs before invoking a destructiveHint=true operation and is not derivable from the annotations or schema alone.

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-loads the core action and packs the confirmation workflow and billing caveats efficiently with no filler. It is slightly dense in the middle, chaining confirmation steps and the task-id handoff in a single stretch, but every sentence carries operational value.

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 an 11-parameter, non-idempotent, cost-incurring mutation, it covers purpose, confirmation gating, billing limits, and the asynchronous follow-up. Since an output schema exists, the brief 'returns a task id; follow it with get_tasks' is sufficient return-value guidance.

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

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

Schema coverage is 100%, so parameter meanings are already fully documented. The description's notes on model defaults, required prompts, and direction are essentially restatements of schema text, adding little beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('Add generated footage to the end ... of a video') and pins down the input type (a VerseIn media URL) plus the model-dependent direction nuance. An agent can immediately distinguish this from generate_video and edit_video.

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?

Describes the price-confirmation workflow step by step ('returns needs_confirmation with a confirmation_token; ask the user, then call again with it') and names the follow-up tool (get_tasks). It lacks an explicit comparison to edit_video or generate_video, which is the only missing routing cue among a large sibling set.

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 destructiveHint=true and readOnlyHint=false, but the description adds the crucial business behavior an agent could not infer: it spends coins, has a confirmation threshold that returns needs_confirmation + token, and refuses face-swap/identity requests. It also notes that unlimited-plan allowances do not apply, which is a non-obvious billing caveat.

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 critical constraints (coin spend, estimate first, refusal policy) are front-loaded in the first few clauses, and every sentence carries operational information. There is minor redundancy between 'Spends the user's coins' and the closing 'charged in VerseIn coins' sentence, but the density is justified for a paid, multi-step, destructive operation.

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 destructive, billable, asynchronous generation tool, the description covers cost estimation, the confirmation handshake, follow-up via get_tasks, and the prohibited-use policy. Since an output schema exists, return-value detail is correctly omitted, leaving no material gap for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents items, request_id, max_total_coins and confirmation_token individually; the baseline would be 3. The description adds cross-parameter workflow meaning — the token is 'passed back' after confirming a price and the retry loop is described — which helps the agent order its calls, but it does not add per-field syntax beyond the schema.

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

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

States a specific verb and resource plus scope: 'Generate 1–12 images (text-to-image, or edit/combine images passed as VerseIn media URLs).' It also implicitly separates itself from siblings like generate_video, upscale_image, relight_image and edit_video by naming the exact modality and the edit/combine mode.

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 preconditions and sequencing: 'call estimate_cost first and tell the user the price', then re-call with a confirmation_token, then follow task ids with get_tasks. It also states an explicit exclusion ('Never use it to swap faces or to put a real person's face or identity onto someone else'), so both when-to-use and when-not-to-use are covered.

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

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

Annotations only say destructive/not read-only; the description adds the critical facts an agent needs: the call spends user coins, unlimited-plan allowances do not apply, calls above a threshold return needs_confirmation, and refusal behavior for face-swap requests. It also flags that reference video length is priced.

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

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

A single dense paragraph, front-loaded with the capability then the cost/confirmation workflow. Nearly every clause carries operational information, though the parenthetical about reference_videos_max is syntactically heavy and could be split for readability.

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

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

For a costly, destructive, multi-item generation tool this covers everything the agent needs: cost estimation, confirmation loop, idempotency via request_id (in schema), return values (task ids followed by get_tasks), and the refusal policy. An output schema exists, so return-format detail is correctly omitted.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a little beyond the schema — that reference videos are only usable for models whose reference mode lists reference_videos_max and that their length counts toward price — but the confirmation_token and max_total_coins mechanics are largely restated from the schema descriptions.

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: 'Generate 1–12 videos from text, a first frame, first and last frames, or reference images and videos.' The input modes named map to distinct parameters, and the tool is clearly separable from siblings like generate_image, extend_video, and edit_video.

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 explicit workflow instructions: call estimate_cost first, tell the user the price, handle needs_confirmation by asking the user and re-calling with the token, then follow task ids with get_tasks. It also names when-not-to-use (face swapping / real-person identity) and states such requests are refused.

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 non-idempotence, so safety is covered. The description adds that the response concerns the user's own balance and expiring coins, but does not clarify account scoping or freshness. With annotations carrying the behavioral bar, this is sufficient but minimal.

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

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

A single front-loaded sentence with no filler. Every phrase earns its place by naming the resource and the extra expiring-coins detail.

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?

A zero-parameter, read-only tool with annotations covering safety and an output schema defining the return shape. The description adds the one useful semantic detail, that expiring coins are included, so nothing essential is missing.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no inputs are 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 ('Get') and resource ('the user's VerseIn coin balance') plus a secondary detail ('next coins to expire'). No sibling tool overlaps with this account-balance purpose, so an agent can identify it immediately.

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 read-only nature and resource name imply when to call it, but the description offers no explicit when/when-not guidance or alternatives. Given no sibling is a close substitute, this is adequate but not instructive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the response is a capability manifest of accepted values, which is useful context, but it says nothing about the odd idempotentHint=false on a read tool or about error behavior for an invalid model key.

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

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

A single front-loaded sentence with no filler; the enumerated capability list is dense and immediately useful for deciding whether to call it.

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 tool with annotations and an output schema, the description covers the essential question (what does it tell me about a model). It could go slightly further by stating it must be called before generating with an unfamiliar model, but nothing critical 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?

With schema description coverage at 100% and one required parameter fully documented as 'model key from list_models', the baseline of 3 applies. The description never mentions the model parameter, adding no semantics beyond the schema.

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

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

Specific verb (Get) plus resource (a model's accepted settings) with an enumerated payload (durations, aspect ratios, resolutions, image modes/limits, audio support). An agent can tell this apart from list_models, but there is no explicit statement distinguishing it from settings_read or pick_model beyond the 'model' framing.

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

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

No explicit when-to-use or when-not language; the guidance is implied (inspect a model's valid parameters before calling generate_video/generate_image). The only routing hint, 'model key from list_models', lives in the schema rather than the description.

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

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

Annotations already establish readOnlyHint=true and a closed-world scope, so safety is covered. The description adds genuinely new context: the polling cadence, the fact that results appear only when finished, and that video tasks carry a poster image. It does not say whether task records expire or how long they remain retrievable, which limits completeness slightly.

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 tightly written sentences: the first covers what is returned, the second covers how to use it. Nothing is redundant and the most important capability is front-loaded.

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?

An output schema exists, so return values need no further explanation, and the description still usefully previews them. Between annotations and schema all the operational essentials are present; only edge cases like id discovery and task expiry are absent.

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

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

Schema coverage is 100% and the single param already documents 'todos' semantics with minItems 1 and maxItems 12. The description's '1–12 tasks' merely restates those bounds and adds no format or id-origin guidance, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Check 1–12 tasks') and enumerates what comes back: status, progress, result URL, and a poster image for videos. It implicitly distinguishes itself from list_recent_tasks by taking explicit ids, but never names that sibling, so an agent must infer which one to call.

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

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

The description gives explicit operational guidance — 'Poll every 15–30 seconds while tasks are queued or running' — which is exactly the when-to-use information an agent needs. It stops short of exclusions (e.g., 'do not poll finished tasks', 'use list_recent_tasks to discover ids').

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

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

The annotations already disclose that this is a mutating, open-world, non-idempotent, non-destructive operation. The description adds valuable context by naming the accepted sources and explaining that the result is a media_url for generation tools, though it does not discuss auth, rate limits, or duplicate handling.

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

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

The description is two tight sentences with no wasted words. The core action and return value are front-loaded and easy to scan.

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 a rich input schema, an output schema, and annotations, the description provides the essential context for calling the tool. It does not clarify whether at least one of url or file must be supplied, even though the schema lists zero required parameters.

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

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

Schema description coverage is 100%, and the schema already documents the url and file parameters in detail. The description restates the same source concepts but adds no extra syntax, format, or one-of constraint beyond what the schema provides.

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

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

The description gives a specific verb, resource, source, and return value: import an image or video from a public https link or attached file and return a media_url. It clearly distinguishes importing existing media from generation tools, but does not explicitly differentiate it from siblings like create_upload or pick_media.

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 implied by the source types and the note that the returned media_url is for generation tools. However, it does not explicitly say when to use this versus create_upload or pick_media, nor does it state when not to use it.

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 readOnlyHint, openWorldHint, and idempotentHint. The description adds that results are scoped to the account and includes a one-line description and starting price, but since an output schema exists, return details are redundant. It adds some context but not substantial behavioral depth beyond annotations.

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

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

Two sentences with the core purpose front-loaded and the alternative stated immediately after. No wasted words, and the structure is easy to parse.

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

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

Given the presence of annotations, an output schema, and full schema description coverage, the description provides everything necessary to understand the tool's purpose and routing. It does not need to explain return values or parameter details because those are covered elsewhere.

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

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

Schema coverage is 100% and the single parameter (media) has an enum and a description in the schema. The tool description does not mention the media parameter at all, so the schema alone carries the full burden, making a 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?

The description states a specific verb (List), resource (image and video models), and scope (available to this VerseIn account). It also distinguishes itself from the sibling get_model, which is for a model's settings, giving an agent enough to tell them apart.

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 explicitly directs the agent to use get_model for a model's settings, clearly establishing the alternative for a closely related operation. This leaves little ambiguity about when to use list_models versus its most similar sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds result ordering ('newest first') and that results span web and app sessions, but says nothing about pagination behavior, result volume, or what an offset beyond the range does — for a paged list tool that is a real gap.

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

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

A single sentence with zero filler, and the most important facts — recency ordering and cross-platform scope — are front-loaded.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What's left thin is paging guidance (an agent can't tell how to iterate offset) and any hint about typical result counts, but for a simple read-only list tool this is nearly 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?

Schema coverage is 67%: limit (max 50, default 20) and media (image/video enum) are well documented, while offset has no description at all. The description adds nothing about filtering or paging semantics, so the undocumented offset parameter remains unexplained in both places.

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 user's recent image and video tasks') plus ordering ('newest first') and scope ('ones made on the web or in the app'). It is clearly different from get_tasks by being a recency listing rather than an ID lookup, though it never names that sibling 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?

Usage is implied by 'recent' and the media filter, but there is no explicit when-to-use or when-not-to-use guidance relative to get_tasks or the create/generate tools. An agent must infer that this is the discovery entry point for past work.

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 trailing "Read-only" is largely redundant. The description does add useful context about what the home page surfaces, but says nothing about idempotency, side effects on navigation state, or what the agent gains by opening it.

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 purpose, then the page contents. Efficient overall, though the closing "Read-only" fragment duplicates the annotation and earns little.

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?

An output schema exists, so return values need no explanation. The description covers what the page contains and the trigger context; only the relationship to sibling navigation tools is 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No parameter claims are made or 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 ("Open VerseIn's home page") and then enumerates the page contents (prompt box, starter ideas, workflows, recent creations), which distinguishes it from siblings like open_library and open_thread_tray. An agent can tell what this returns 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?

"Opened by the user from the sidebar" implies this is a user-triggered navigation action, giving some context. But it never says when an agent should choose this over open_library or open_thread_tray, nor when not to call it. Usage is inferable 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 readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered, and the trailing 'Read-only' restates it redundantly. What the description does add is content scope: it names exactly what the library surfaces (recent media, in-progress tasks, coin balance). It does not say how many items 'recent' means or whether opening has side effects on UI 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 short sentences, front-loaded with what the tool contains before the usage trigger, with no filler. The final 'Read-only' sentence is the only near-waste since annotations already state it, keeping this just short of 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 zero required parameters, one optional enum-filtered parameter, full schema coverage, and an output schema, the description covers purpose, trigger, and safety adequately. The remaining ambiguity is whether 'Open' is a UI navigation action versus a data fetch, and how much content 'recent' returns.

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 `media` parameter is fully documented in the schema, including the enum (image/video) and the 'omit for both' default behavior, so the description is not obliged to repeat it. It adds nothing about filtering semantics beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description uses a concrete verb ('Open') and resource ('VerseIn library') and itemizes its contents: recent images and videos, tasks in progress, coin balance. It is clearly distinguishable from generation/editing siblings, though it overlaps in scope with get_balance, get_tasks, and list_recent_tasks without saying how it differs from 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 an explicit trigger condition: 'Use when the user wants to browse, find, or reuse something they made before,' which is clear context for invocation. It stops short of exclusion criteria — nothing tells the agent to prefer get_tasks or get_balance for the overlapping data.

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, and the description's 'Read-only' merely restates that. The one piece of added value is disclosing that in-progress tasks are returned alongside finished assets, but it says nothing about ordering, counts, or freshness of task status.

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 resource and its contents. 'Takes no arguments' and 'Read-only' duplicate the empty schema and readOnly annotation, so they are slightly wasted words.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description covers both finished and running items. A note on how running tasks are surfaced or ordered would make it 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?

Zero parameters, so the baseline applies; 'Takes no arguments' is consistent with the empty schema and correctly tells the agent nothing must be supplied.

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 the works generated in this chat') and enumerates the contents: finished images and videos plus still-running tasks. The 'in this chat' scoping clearly separates it from global siblings like get_tasks and list_recent_tasks.

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 selecting condition: 'Use when the user wants to see what was made in this conversation.' However it never names the near-twin alternatives (get_tasks, list_recent_tasks) or says when those are preferred instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered, and the description adds genuinely useful behavior: it is an interactive picker, template/character works are excluded, and on hosts without pickers it degrades to listing recent works requiring a text fallback. It does not explain the non-idempotent nature of the interaction or what happens on cancel, but the added context is solid for an annotated tool.

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

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

Each sentence carries distinct information: capability, return value, trigger, exclusion, fallback, and alternative tool. The first sentence is long and packs the thumbnail picker, media types and three use cases together, but nothing is 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?

An output schema exists so return values need no elaboration, and the description still notes it returns chosen media URLs. With fallback behavior, exclusions, and the create_upload pointer all covered, an agent has everything needed to call this correctly or route elsewhere.

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

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

Schema description coverage is 100%, with each of max, media and purpose documented including defaults and bounds, so the baseline is 3. The description only echoes the semantics via 'one or more' and 'images or videos' and says nothing about the purpose parameter's prompt-wording role.

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: 'Let the user choose one or more of their recent finished images or videos from a picker with thumbnails,' plus the downstream use (reference, first frame, edit source). It is clearly distinguishable from siblings like create_upload and import_media_from_url, which it explicitly calls out.

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

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

Gives an explicit trigger ('when the user refers to an earlier work without naming one'), an explicit exclusion ('Works made with templates or characters are not listed'), and an explicit alternative ('A new file needs create_upload instead'). It also handles the degraded-host case and tells the agent what to do there (ask the user in text).

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 beyond the annotations by disclosing the return contract (model key, plus aspect ratio/resolution/duration with ask_params) and, importantly, host-dependent degradation to a text list. It does not say whether the picker blocks, what a cancel yields, or how long it waits, which matters for a UI-interaction tool with idempotentHint=false.

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 sentences, front-loaded with the action and the picker's nature, then usage, then exclusions, then return/fallback. No sentence is redundant.

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

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

With an output schema and annotations present, the description need not explain return values, yet it does so usefully and covers the host fallback. The remaining gap is interaction semantics on cancel or timeout, which an agent calling a user-facing picker would benefit from knowing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds downstream meaning for ask_params (it yields aspect ratio, resolution and duration) that the schema only restates as a prompt, giving a small lift above baseline; media and need are left entirely to the schema.

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

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

States a specific verb and resource: let the user choose an image or video model from a picker, and names the picker's content (logos, starting prices). It is clearly distinguishable from sibling model tools like list_models and get_model, which do not prompt the user.

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 both directions explicitly: use when the user has not named a model or asks to choose one, do not call when a model is already named. It also supplies a fallback path for hosts without pickers, so the agent knows what to do if the call degrades.

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 (destructiveHint=true) by disclosing the coin cost model, the confirmation-threshold flow, the confirmation_token mechanics, the returned task id and the follow-up tool, and that unlimited-plan allowances do not apply. The request_id charge-idempotency note adds context the annotations cannot express.

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

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

Front-loaded with the core action, then cost and confirmation flow, then return/follow-up. The final two sentences ('charged in VerseIn coins', 'unlimited-plan allowances do not apply') partly restate the earlier 'Spends the user's coins' line, a small redundancy that 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?

For an 11-parameter generative mutation with an output schema, the description covers the essentials: cost and approval gating, token round-trip, and what to do after the call (get_tasks). Return-value detail is correctly left to the output schema.

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

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

Schema coverage is 73%, so the schema already documents aspect_ratio, prompt, max_total_coins, confirmation_token and request_id in detail. The description reinforces the confirmation_token and cost workflow but adds little about the placement coordinates (x_start/x_end/y_start/y_end) or resolution that is not already in the schema; baseline 3 applies.

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

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

States a specific verb (reframe / change aspect ratio) and resource (a video, a VerseIn media URL) plus the distinctive behavior of filling new areas with generated content. This separates it clearly from edit_video, extend_video and upscale_video without needing to open 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?

Gives clear operational guidance: prices depend on length, above-threshold calls return needs_confirmation with a token, the user must be asked, then the call is repeated with the token, and the task is followed via get_tasks. It does not explicitly state when to pick this over edit_video, so it falls 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?

Goes well past annotations by disclosing coin spend, the confirmation threshold and needs_confirmation response shape, that unlimited-plan allowances are excluded, and the task-id/polling model. The annotations only flag non-read-only/destructive; the description supplies the cost and consent semantics an agent needs.

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

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

Four tight sentences front-load the action, then cost, then confirmation mechanics, then output handoff. Dense but no filler; the only overlap is restating the confirmation token, which the schema also covers.

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 9-parameter, coin-charging mutation with an output schema, the definition covers the critical unknowns: pricing, consent threshold, retry safety, and task polling. Gaps are minor — it doesn't say where to obtain valid preset keys or how speed tiers affect cost beyond 'slower costs more'.

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

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

Schema coverage is 100% and each parameter (mode, preset, prompt, max_total_coins, confirmation_token) already carries a detailed description. The description restates the preset/text duality and the confirmation token round-trip but adds no syntax or format detail beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('Change the lighting of an image') and enumerates both input modes (preset or text description), plus the image must be a VerseIn media URL. This cleanly distinguishes it from siblings like relight_video, generate_image, and upscale_image.

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

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

Explains the confirmation flow explicitly (ask the user, retry with confirmation_token) and directs follow-up to get_tasks. It does not name alternatives such as relight_video for video assets or estimate_cost for pre-pricing, so the when-not guidance is implied rather than stated.

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?

Substantially exceeds what annotations provide: pricing depends on video length, a backup-model fallback may raise cost up to a quoted ceiling, allowance plans do not apply, and the two-step confirmation protocol is spelled out. These are cost/authorization behaviors an agent cannot infer from destructiveHint=true or openWorldHint=false.

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 in the first clause, followed by cost, confirmation, and return-value handling in a logical order. Slightly dense in the billing region ('Spends the user's coins... charged in VerseIn coins... allowances do not apply'), where two sentences could be tightened into one without losing 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?

For a 9-parameter cost-incurring mutation with an output schema, the description covers the critical unknowns: billing, confirmation, idempotent retry framing, and follow-up task polling. It omits nothing blocking, though it says nothing about failure/refund behavior when a job errors after charging.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: the relationship between the quoted ceiling (max_total_coins), the confirmation threshold, and the returned confirmation_token as a retry loop. It also frames preset/prompt/reference as mutually alternative control modes.

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 ('Change the lighting of a video') and enumerates the three input modes (preset, text direction, reference image), which cleanly separates it from relight_image and edit_video. An agent can identify the tool's job 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 explicit operational context: when a ceiling exceeds the threshold the call returns needs_confirmation, the agent must ask the user, then retry with the token; results are followed via get_tasks. It does not explicitly contrast with relight_image or edit_video, so it stops short of full alternative routing.

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

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

Annotations already cover read-only and closed-world safety. The description adds the behavioral context annotations cannot: it is host-invoked on each keystroke and is off-limits to assistants. It doesn't discuss result size or latency, but with an output schema present that's a minor gap.

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, zero waste. The prohibition is stated up front rather than buried, so an agent scanning quickly will not mistakenly invoke it.

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 tool with an output schema and full annotation coverage, everything needed to avoid calling it and to understand its context is present. Only search semantics (what fields match) are left unstated.

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

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

Schema description coverage is 100% for the single 'query' parameter, including the 'may be empty' edge case, so the schema does the heavy lifting. The description adds no matching-syntax or format detail beyond it; baseline 3 applies.

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

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

States a specific verb and resource ('Search the user's finished VerseIn images and videos') plus the consumer context ('composer @-mention picker'), so the agent knows exactly what is searched and why. It doesn't need sibling differentiation because no sibling overlaps, but it also doesn't say what it searches by (titles, tags, captions).

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 when ('Called by the host while the user types') and an unambiguous when-not ('assistants must not call it'). That negative directive is the single most decision-relevant instruction in the definition and it is stated directly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description reinforces read-only and adds genuinely new context: the values are user-controlled, and it names what each setting means. It does not reconcile the unusual idempotentHint=false on a pure read, but that is a minor omission given the annotation coverage.

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, zero waste, with the field enumeration front-loaded and the read-only constraint placed last as a qualifier. Every clause carries information an agent needs.

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 an output schema present, return shape needn't be described, and the read-only behavior is stated. The only loose end is what the tool returns before the user has configured anything, or whether any auth/setup is required – minor, but a real gap for a first-run 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?

Zero parameters, so the baseline is 4. The description productively uses the space to describe the fields in the response rather than invent parameter semantics that do not exist.

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

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

States a specific verb (Read) and resource (VerseIn plugin settings), then enumerates the exact four fields returned: default image model, default video model, default aspect ratio, and the coin spend threshold. This makes it immediately distinguishable from settings_update and from the model-listing 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?

The clause 'the user changes them in the plugin settings' signals this tool is read-only and that settings mutation is out of scope for the agent, which implicitly excludes the write path. It stops short of naming settings_update as the alternative, so the exclusion is inferential 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 non-read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered structurally. The description adds the crucial access-control fact that this is a UI-only path assistants should not invoke. It does not describe merge semantics, but the schema already says unspecified settings remain unchanged.

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

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

Two short sentences, zero waste, with the gating restriction front-loaded after the purpose. Nothing is buried or 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?

An output schema exists and parameters are fully documented, so the description does not need to explain return values. Purpose plus access restriction are sufficient for correct handling; only minor details (validation failure behavior) are absent.

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

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

Schema coverage is 100%: the nested 'set' object documents each recognized setting name, enum values, and the partial-update rule ('others stay as they are'). The description adds no meaningful parameter detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Change VerseIn plugin settings') in the first clause, so the mutation target is unambiguous. It does not explicitly differentiate from the sibling settings_read, though 'Change' implies the counterpart.

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

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

Explicitly states who may call it ('plugin settings page only') and flatly excludes the reader ('assistants must not call it'). This is a rare, unambiguous negative-usage instruction that directly prevents misselection by an agent.

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

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

Beyond the annotations, the description discloses the critical cost behavior: coins are spent, price depends on image size, calls above a threshold return needs_confirmation with a token, and the user must be asked before retrying. It also explains that the result is a task id to follow with get_tasks and that unlimited-plan allowances do not apply.

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 front-loaded with the core action and immediately follows with the financial and confirmation constraints. Despite a small amount of repeated cost language, every sentence contributes to safe invocation of a paid, confirmation-gated tool.

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 14-parameter paid mutation tool with a fully described schema and an output schema, the description supplies the missing workflow context: pricing, confirmation token handling, task follow-up, and plan limitations. Nothing essential for correct invocation is omitted.

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 each of the 14 parameters is already documented in the schema. The description explains the surrounding confirmation flow and cost context but adds little parameter-specific meaning beyond what the schema provides, 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?

The description opens with a specific verb and resource: 'Upscale an image ... to a higher resolution.' It also identifies the required input as a VerseIn media URL, which clearly separates it from video/image generation and relighting 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?

Usage context is clear for upscaling an image, and the confirmation workflow is described. However, it does not explicitly name when to choose upscale_image over alternatives such as upscale_video or generate_image, so it falls short of full alternatives 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?

Beyond the annotations, the description discloses key behavior: it spends the user's coins, price depends on length/settings, high-cost calls require explicit confirmation with a token, it returns a task id for follow-up, and AI-assistant generation is charged in VerseIn coins with unlimited-plan allowances not applying. These details materially help the agent avoid unexpected charges and handle the confirmation workflow correctly.

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 front-loaded with the core action and then covers cost, confirmation, and follow-up. It is dense and mostly earns its space, though the charging point is restated slightly across sentences ('Spends the user's coins' and 'Generating through an AI assistant is charged in VerseIn coins').

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

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

Given a 10-parameter tool with 100% schema coverage and an output schema, the description supplies the behavioral context the schema cannot: cost implications, the confirmation threshold and token flow, and the need to follow up with 'get_tasks.' An agent has enough information to invoke it and handle the main edge cases 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 the schema itself already explains all 10 parameters. The description adds some workflow context around cost and confirmation tokens, but it does not add parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate when the schema carries full parameter documentation.

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 and resource: 'Upscale a video ... to a higher resolution or frame rate,' and identifies the input as 'a VerseIn media URL.' This is clear enough to distinguish it from image upscaling by resource and from edit/reframe/extend by purpose, though it does not explicitly name sibling alternatives.

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 clear operational context: the call spends coins, priced by video length and settings, and calls over the confirmation threshold return 'needs_confirmation'; the agent should ask the user and retry with the token. It also directs the agent to follow the returned task id with 'get_tasks.' It does not state when to choose this over editing, reframing, or extending a video, so it stops short of full alternative routing.

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