VideoUpscaler

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

With no annotations present, the description carries the full disclosure burden and does most of it: it reveals the 100MB cap, the 1-hour expiry of the signed URL, and the non-obvious auth rule that the PUT must omit Authorization. It stops short of failure semantics — what happens on an expired URL, a size mismatch, or an unsupported byte payload.

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 tightly packed sentences: purpose and precondition first, then the exact call sequence, then the expiry caveat. Every sentence carries information an agent cannot get from structured fields.

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

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

There is no output schema, but the description names the returned artifacts (upload_url, headers, video_url) that the agent must consume, so the missing output schema is compensated. For a two-parameter presign tool, nothing needed to call it correctly is absent beyond error handling.

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 50% (content_type has only an enum, no prose), so the description needs to compensate, and it does add a real constraint the schema does not express: the 100MB practical limit, since the schema's maximum is 2^53. It does not explicitly tie content_type to the accepted video containers, leaving that mapping implicit in 'local video file'.

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 (get a signed upload URL for a local video file) with the exact precondition 'when it has no public URL'. It also names the downstream sibling upscale_video, so the agent can place this tool in the workflow without inspecting the other schemas.

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

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

Gives an explicit trigger condition (no public URL available), an ordered procedure (PUT bytes to upload_url with returned headers, then pass video_url to upscale_video), and an exclusions-style note that no Authorization header should be sent. There is no ambiguity about when to reach for this versus upscale_video.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the annotation carries the safety burden. The description adds real value by disclosing the return contents (balance plus per-resolution pricing), which matters most here because there is no output schema. It stops short of noting currency, units, or whether pricing can change.

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 that front-loads the most important return value (credit balance) and then the secondary one. 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-parameter read with no output schema, the description adequately covers what comes back, which is the only thing an agent needs to decide to call it. Minor gaps remain around currency/units and whether the pricing list is exhaustive for all resolutions.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema's empty properties object matches the description's non-mention of 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?

Rather than restating the name, the description states the concrete payload: credit balance and per-resolution price per second of video. That tells an agent exactly what 'account' means here, and no sibling (create_upload, get_task, list_tasks, upscale_video) covers the same resource. It lacks an explicit verb but the resource is unambiguous.

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

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

Usage is only implied: an agent can infer this is the tool to call to check credits before or after an upload. There is no explicit 'use this when...' statement, no mention of alternatives, and no note that it takes no arguments, which would have made it clearly self-selecting.

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

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

The description adds substantial behavior beyond the readOnlyHint annotation: task statuses, that completed tasks expose output_url, that failed tasks refund credits, and that wait_seconds can block up to 45 seconds. It omits edge cases such as missing or expired task IDs, but overall it is quite transparent.

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 and compact: purpose first, then status semantics, then wait/polling behavior. Every sentence adds useful information without repetition.

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

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

For a simple read tool with no output schema and no schema descriptions, the description covers the important return semantics through statuses and output_url, plus polling behavior. The main remaining gap is that it does not explain the task_id source or not-found behavior.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains wait_seconds behavior and its 45-second cap well, but it never mentions the required task_id parameter or where to obtain it.

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 clear verb and resource: get an upscale task. It is distinguishable from list_tasks by the singular retrieval framing, but it does not explicitly name sibling tools or explain its relationship to upscale_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 useful polling guidance: set wait_seconds to wait before returning, and call again if the task is still running. However, it does not state when to use this tool instead of list_tasks or how task_id is obtained, so usage is only implied.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, so the description adds some value by disclosing ordering ("newest first") and scope ("including ones started on the website"). However, it does not mention pagination behavior, default limit behavior, or any auth/rate-limit context beyond the annotation.

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

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

The description is a single efficient sentence with zero waste. It is front-loaded with the action and resource, then adds ordering and scope details.

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 read-only list tool with one optional parameter, the description covers purpose, ordering, and cross-source inclusion well. It is slightly incomplete because it does not explain the limit parameter or pagination behavior, but no output schema exists and the annotation already carries the safety profile.

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 for the single limit parameter is 0%, and the description does not mention the parameter at all. The parameter name "limit" is fairly intuitive, but the description adds no meaning about what it limits, its default, or how it interacts with the maximum of 50.

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

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

The description gives a clear verb and resource ("List your upscale tasks") and adds useful scope details: newest first and includes website-started tasks. It implicitly separates itself from get_task by being a plural listing operation, 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?

The phrase "List your upscale tasks" implies the tool should be used when the agent needs a task list, but there is no explicit guidance on when not to use it or when to prefer get_task instead. The usage context is present but left implicit.

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

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

With no annotations, the description carries the full burden and does so well: it discloses credit charging for the entire video, that length is read from the file, that it returns a task (async), and that downloading large videos takes minutes. It does not say how to retrieve the finished result (presumably get_task) or whether a webhook replaces polling, which keeps it from a 5.

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

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

Three sentences, front-loaded with the action and outputs, then cost/duration, then failure recovery. No sentence is filler and the most decision-relevant facts come first.

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

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

For a credit-charging async job with a nested ops object and no output schema, the description covers cost, limits-by-reference, async return, and retry semantics. The remaining gap is how to obtain the result (poll get_task vs. wait for webhook), which the agent must infer from sibling names.

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 schema already documents all five parameters; baseline is 3. The description adds real semantic weight only to idempotency_key (a new key re-charges credits), which is the one parameter whose misuse has a monetary cost.

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 upscaling a video') plus the exact target outputs (1080p, 2k, 4k). No sibling (create_upload, get_task, list_tasks, get_account) could be confused with it.

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 routing: on timeout or failure, call list_tasks first and retry only with the SAME idempotency_key. It also names the consequence of violating that rule (a new key charges again), so the agent knows both when to use the tool and how to recover.

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