Phoenix Labs

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety and repeatability are covered. The description adds genuinely new behavior: the job's price is refunded to the balance 'at once', telling the agent the side effect is financial and immediate.

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?

One sentence, front-loaded with the action and its precondition, with the refund outcome trailing. Nothing is padding.

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-parameter mutation with no output schema, the description covers the eligibility precondition and the refund side effect, which is most of what an agent needs. It does not say whether an ineligible job returns an error or what the response body contains, 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?

Schema coverage is 100% and the single job_id parameter is already documented with its cloud_/motion_ prefixes. The description adds no format, validation, or lookup 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?

Names a specific verb (cancel) with the exact resource and scope: a restore or clip whose file was never uploaded. An agent can distinguish it from create_restore, start_clip, and start_restore 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?

The phrase 'whose file was never uploaded' implicitly scopes usage to unstarted jobs and rules out cancelling in-progress work, which is real context. It never names an alternative tool or states what to do if the job has already started, so it falls short of a full when/when-not statement.

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 the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds substantial context beyond that: it returns an upload_url rather than performing the upload, charges are refunded to balance on failure, the GPU revalidates real file size/duration and refuses mismatched files, and there are hard caps (2 GB; 30 min standard, 6 min enhanced/studio_max).

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 before workflow, payment, and limits, and every sentence carries information. It is dense and packs four distinct topics into one block, which slightly hurts scanability, but nothing is wasted.

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 creation tool with no output schema, the description covers the full lifecycle: what is produced (an upload_url), the required follow-up call, both billing modes and the failure-refund behavior, and the size/duration limits the GPU enforces. An agent has enough to invoke it correctly without further context.

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 a constraint not present in any parameter description: duration ceilings that differ by quality tier (standard 30 minutes vs enhanced/studio_max 6 minutes). The pay_with and 2 GB notes largely restate the schema, so it is a modest rather than large increment.

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 a cloud restore of an old video) plus the actual processing performed (denoise, deinterlace, rebuild detail, upscale). It clearly distinguishes itself from the sibling start_restore by describing itself as the step that returns an upload_url, and from quote_restore/get_restore by being the initiation step.

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 sequencing guidance: PUT the video to the returned upload_url, then call start_restore. It also spells out the two payment paths (balance with an agent key vs checkout link returned by start_restore). It does not mention quote_restore as a pricing precondition or state when not to use it, so it stops short of 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 the write/non-idempotent/non-destructive profile, so the bar is lower. The description adds genuinely new behavioral context: nothing is charged until the user pays, which tells the agent this call creates an unpaid instrument rather than moving money. It does not disclose link expiry or reuse 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?

A single sentence with the artifact, purpose, range, and payment timing front-loaded. Nothing is wasted and nothing important is buried.

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

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

For a two-parameter tool with full schema coverage and no output schema, the definition is nearly complete. The only real gap is what the call returns (presumably a URL) and whether the link expires, which an agent might want before presenting it to a user.

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 both parameters (email and amount_usd) are already documented in the schema, including the same $5–$200 bound repeated in the description. The description adds no syntax or format detail beyond the schema.

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

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

The sentence names a concrete artifact (a checkout link) and its effect (adds money to the balance, with a stated $5–$200 range), so an agent knows exactly what is produced. It does not, however, distinguish itself from the sibling top_up_with_usdc, which is the most likely alternative for the same user goal.

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

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

Usage is only implied: an agent can infer this is for funding a balance via a user-opened link, but there is no explicit when-to-use guidance and no mention of when to prefer top_up_with_usdc instead. Adequate but leaves the sibling choice 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the returned data (limit, spent, left) with no output schema present, which is genuinely useful behavioral 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?

A single sentence with a front-loaded subject and a colon-delimited enumeration of the returned figures. No filler, no repetition of the title.

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-argument read tool with annotations covering safety and no output schema, the description supplies the missing piece by naming what is returned. It stops short of explaining units, currency, or refresh behavior, but nothing essential to calling the tool correctly is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for no-param tools is 4. The description correctly focuses on return content rather than inventing parameter detail.

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 resource (the Phoenix balance spendable by this key) and enumerates the returned figures: balance, limit, amount spent, amount left. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools (none of which appears to fetch a balance anyway).

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 balance this key can spend' suggests a pre-purchase or pre-spend check, but there is no explicit when-to-use statement and no reference to related siblings such as top_up_with_usdc or create_top_up_link that an agent might pair with it. Adequate but with a clear 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavioral context beyond them: result fields only materialize at status 'done', and both URLs expire after 24 hours.

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 compact sentences, front-loaded with the purpose and immediately followed by the conditional result semantics. Every clause carries information an agent needs; 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 must carry return-value semantics. It covers the 'done' case (video_url, download_url, 24h validity) but never enumerates the other possible status values (e.g. processing, failed) or what to do while pending, which is the core use of a status-polling tool.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema itself, including the '(motion_…)' format hint. The description adds no syntax or meaning beyond what the schema already provides, 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+resource ('Status of a clip') and disambiguates it from siblings like make_clip, start_clip, and list_clips by framing it as a status check. It stops short of explicitly saying it is the polling companion to make_clip, so it is clear but not fully differentiated.

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

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

Usage is only implied: the clip_id provenance ('make_clip returned') suggests this is the follow-up poll after creating a clip. There is no explicit when-to-use/when-not statement and no mention of how it relates to list_clips as an alternative.

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. The description adds context the annotations do not carry: the cost model ('Free, no key needed') and the unit of the returned values ('US dollars'), which meaningfully informs invocation.

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 zero filler, front-loading what is returned before the pricing/auth note. 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 lookup with no output schema, the description adequately covers the resource, currency, and access conditions. A brief note on return shape (list vs. per-service tiers) would close the remaining gap, but nothing needed to invoke it correctly 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 the baseline is 4 under the rubric. The description correctly implies no arguments are required by noting no key is needed, and adds nothing misleading about 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?

States a specific verb ('Get') and resource ('current prices and limits for Phoenix Motion clips and Cloud Restore'), with the currency unit specified. It is distinguishable from quote_restore, which presumably returns a per-job quote, but the description never explicitly contrasts the two, so it falls short of the sibling-differentiation bar for a 5.

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?

'Free, no key needed' usefully tells an agent this can be called without authentication, which is a real usage condition. However, there is no explicit guidance on when to use this price list versus quote_restore for a concrete restore cost, leaving the primary alternative unaddressed.

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 safety is covered. The description adds genuinely useful behavior beyond annotations: the meaning of the 'done' status and that the download_url is valid for only 24 hours, which an agent could not infer from the 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?

Two compact sentences, front-loaded with the purpose followed by the success-case payload note. No filler, though it is terse enough to leave the polling flow implicit.

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, so the description usefully names the key return values (status, download_url) and their lifetime. Combined with the 100%-covered input schema and read-only annotations, an agent has enough to poll and consume the result correctly.

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

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

Schema coverage is 100% and the single job_id parameter already documents its origin and cloud_ format, so the description adds no parameter meaning. Baseline 3 applies when the schema does the heavy lifting.

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 resource (a restore) and implied action (check its status), which is distinguishable from siblings like create_restore, start_restore, and quote_restore. It is clear but does not explicitly contrast itself with those 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 is only implied: the schema note ties job_id to create_restore's return, and the description hints at polling until status is 'done'. There is no explicit statement of when to call this versus alternatives such as quote_restore or cancel_job.

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 by structured data. The description adds useful context that results are limited to 'most recent' and sorted newest-first, but does not disclose how many clips are returned, whether the list is truncated, or any rate-limit/pagination 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?

A single sentence with no filler, and the two facts that matter (scope and ordering) are front-loaded. Every word earns its place.

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

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

For a zero-parameter, non-destructive list tool whose annotations already carry the safety profile, the description is nearly sufficient. The remaining gap is that with no output schema and no stated cap, an agent cannot tell how many clips 'most recent' yields or whether it must page through results.

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 no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing inputs and instead documents the implicit scoping ('this key') and ordering of the result set.

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?

Names a specific verb (list) and resource (clips), adds scope ('made with this key') and ordering ('newest first'), so an agent knows this is a scoped, ordered enumeration rather than a single fetch. It does not explicitly name the sibling get_clip or explain how the two differ, which is the only thing keeping it from a 5.

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

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

Usage is only implied by the phrasing 'the most recent clips made with this key' - an agent can infer this is the bulk/recent-history call as opposed to get_clip for one clip, but no when-to-use, when-not-to-use, or alternative is stated. 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?

Beyond the annotations (which only flag non-read-only, open-world, non-idempotent, non-destructive), the description discloses billing behavior ('costs the listed price from the balance; a clip that fails or is refused costs nothing') and the async upload handshake. It doesn't cover polling or how to retrieve the result, which is a minor gap for a job-producing 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?

The description is two dense sentences with no filler, and the core purpose and cost model are front-loaded. Slightly packed but 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?

For an async, paid generation tool with no output schema, it covers cost, failure charging, and the two start paths. It omits what happens after start_clip (e.g., polling via get_clip), which keeps it just short of 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 description coverage is 100%, so the parameters are already fully documented, including loop, seed, size costs, and content_type usage. The description reinforces image_url's effect (starts immediately) but adds little 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?

The description names a specific verb and resource ('turn one still image into a five-second video clip at 24 fps, with sound'), including the model name Phoenix Motion and the output specs. This clearly distinguishes the tool from start_clip, get_clip and list_clips.

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

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

It gives two concrete invocation paths: pass image_url to start at once, otherwise upload to the returned upload_url and call start_clip. It also points to get_prices for cost. It does not explicitly state when to choose make_clip over start_clip in the upload case, but the branching is clear.

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 safety is covered. The description adds real value beyond them by stating the call is free, requires no API key, and returns an exact (not estimated) figure – behavioral facts an agent cannot get from structured fields.

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 zero waste: the core purpose is front-loaded and the auth/cost note follows immediately. Nothing could be cut 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 simple quote tool with 100% param coverage and no output schema, the description covers purpose, pricing basis, and auth/cost behavior adequately. It stops short of describing the returned quote shape (single number vs breakdown), the only meaningful 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?

Schema coverage is 100%, with rich enum descriptions for quality and defaults documented for width/height, so the schema does the heavy lifting. The description's 'from its length and resolution' only loosely maps the pricing inputs and adds no syntax or format detail beyond the schema.

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

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

The description states a specific verb and resource: computing the exact USD price to restore one video clip, scoped by length and resolution. It distinguishes the tool from siblings like get_prices (general prices) and get_restore (job status) through the 'restore one video clip' framing, though it never names those alternatives 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 rather than stated: an agent can infer this is the pre-flight cost check before create_restore/start_restore, and 'Free, no key needed' usefully signals it can be called without auth or cost. However, there is no explicit when-to-use vs get_prices or create_restore 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 readOnly=false, destructive=false, idempotent=false, and openWorld=false. The description adds the important prerequisite that an image must be uploaded to make_clip's upload_url first, but it omits side effects, authentication needs, rate limits, or what starting the clip actually triggers.

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 the prerequisite front-loaded before the action, using no filler. Every element earns its place.

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

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

For a simple one-parameter job-start tool, the description covers the critical upload-then-start sequence. It does not explain what the tool returns or how to check progress afterward, and there is no output schema to compensate, so it is good but not 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 description coverage is 100%, and clip_id is fully documented in the schema as the ID returned by make_clip. The description reinforces that workflow but adds no parameter syntax or meaning beyond what the schema already 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 states a specific action ('start making the clip') and ties it to the make_clip upload workflow. It distinguishes this tool from make_clip by placing it after the upload step, though it does not explicitly name 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 clearly states when to call it: after uploading the image to make_clip's upload_url. The sequencing is explicit, but it does not explain when not to use this tool or name specific alternatives beyond the implicit make_clip predecessor.

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 a non-read-only, non-idempotent, non-destructive local operation, and the description adds genuinely new context: the call may or may not start work immediately depending on balance, and in the checkout case it returns a URL that the user must open before the restore begins. It does not warn about double-invocation behavior despite 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?

A single dense sentence with the precondition front-loaded and the two outcome branches clearly parallel. No filler, no repetition of the title.

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 explains the key return value (checkout_url) and what triggers it. It leaves the successful balance-paid response shape and post-start polling guidance (e.g., get_restore) unstated, which is a minor gap for a job-launching tool.

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

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

Schema coverage is 100% and the single job_id is already documented in the schema as the value create_restore returned (cloud_…). The description adds no format, prefix, or validation detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("starts a restore") and distinguishes two distinct execution modes: balance-paid (immediate) and checkout (returns checkout_url, starts after payment). The precondition "After the video is uploaded" also positions it in the workflow relative to create_restore, though no sibling is named outright.

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

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

Clearly signals when to call it (after upload / after create_restore produced the job_id) and explains the branch that determines whether money is collected up front. It does not state any exclusions or name alternatives such as quote_restore for pricing, so it stops short of full routing guidance.

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

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

Discloses behavior no annotation covers: a first call without payment returns an x402 PaymentRequired error, the payment must be an EIP-3009 signed transfer passed in _meta['x402/payment'], gas is paid by the facilitator, and the amount range is bounded. This is exactly the non-obvious sequencing an agent needs to avoid mis-calling.

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

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

Three tight sentences, front-loaded with purpose and mechanism, then the call protocol, then cost/range details. Dense but every clause carries operational information; nothing is redundant 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 one parameter, no output schema, and rich annotations, the description covers the full calling protocol including the error path. Minor omissions remain (credit timing, payment expiry/retry semantics) but they are not blocking 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 coverage is 100% and the description repeats the range, but it adds a conversion semantic the schema lacks: 1 USDC adds $1 (and no gas cost), which tells the agent how to compute the amount_usd value.

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 (add money to balance) and resource (balance via USDC on Base) and names the exact mechanism (x402). It is immediately distinguishable from the sibling create_top_up_link because it emphasizes self-payment from a crypto wallet rather than a hosted link.

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 condition ('for assistants that hold a crypto wallet') and lays out the two-call sequence in detail. It does not name create_top_up_link as the alternative for non-wallet assistants, so routing between top-up methods is left partly to inference.

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