Convert.Online

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

Annotations already flag this as a non-read-only, non-idempotent, open-world operation, and the description adds real context: it returns a download link, runs against the caller's account, consumes quota, and caps imports at 20 GB. It does not say whether the call is synchronous or must be polled via the get_job sibling, which is the one behavioral gap an agent would care about.

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 action and the two input paths, with the guidance before the rationale. The aside about relayed calls never arriving and the user watching a spinner is longer than needed to justify the no-inline-bytes rule, but it is confined to one clause.

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

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

No output schema exists, and the description compensates by naming the return value (a download link) and the limits on input size. For a six-parameter tool with a nested options object, the main thing left unsaid is the async/job lifecycle implied by the get_job sibling.

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 meaning the schema does not: source_url and import_id are alternatives, not complements, and options keys must come from list_options rather than being guessed. Filename, input_format, and output_format are left to the schema, which covers them adequately.

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 plus the return value: "Convert a file to another format and return a download link." It also distinguishes itself from siblings by name, routing uploads to create_upload and option discovery to list_options.

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 the two mutually exclusive input paths and the condition that selects each: source_url when the file is already reachable, import_id when the file lives on a device or sandbox. It adds a prerequisite (call list_options before passing options) and an exclusion (no inline bytes).

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 a non-read-only, non-idempotent, non-destructive operation. The description adds real behavior: 20 GB cap (5 GB through the browser link), that the conversion launch is triggered by output_format at upload time rather than a later call, and that convert will block waiting for the bytes. That is substantive beyond the annotation set.

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 decision rule and dense with useful facts per sentence; the only cost is the long em-dash-clause sentences that sprawl slightly. Nothing is filler, but a little tightening would help scanning.

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 carries the return-value burden and does: import_id plus two delivery options, with guidance on which to prefer. Combined with the size limits and the convert follow-up, an agent has everything needed to call this 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 filename, input_format and output_format are already documented. The description restates the meaning of output_format (it drives automatic conversion), which reinforces the schema rather than adding format syntax or constraints the schema lacks. 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 opens with a specific verb and object ('Get somewhere to put a local file') and immediately states the distinguishing scope ('ANY file that is not already at a URL'), which separates it from convert, get_job and list_formats without the agent needing to open a schema.

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

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

It names the condition that selects this tool (file not already at a URL), which of the two delivery paths to use depending on network reach to convert.online/storage, and the required follow-up call to convert. When-to-use, how-to-choose and what-comes-next are all 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=true, and the description adds a meaningful behavioral detail: the download link is only available 'if finished'. This implies the job may still be in progress. It doesn't describe exact status values, but for a simple read-only call this is sufficient context beyond the annotations.

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

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

A single, front-loaded sentence that communicates both the primary purpose and the conditional detail about the download link. No filler, no 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-only status tool with one well-documented parameter, the description is complete. It states what is returned (status, and download link when finished) and the annotations cover the safety profile. No output schema exists, but the description sufficiently sets expectations.

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 parameter description already explains that job_id is returned by convert. The tool description adds no new semantic detail about the parameter itself, so it stays at the baseline for high schema coverage.

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 clearly states a specific verb ('Get'), a concrete resource ('status of a conversion job'), and an additional outcome ('download link if finished'). This distinguishes it from siblings like convert, create_upload, list_formats, and list_options, which serve different purposes.

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 context is clear: this is the polling/status-check tool for an async conversion job. It doesn't explicitly name when not to use it or how it compares to alternatives, but the schema's mention that job_id comes from convert makes the intended workflow evident. No exclusions or conflicting usage guidance are present.

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 signal read-only behavior, and the description adds meaningful conditional behavior: no argument returns all input formats, while input_format narrows results to valid conversions. This is valuable context beyond the schema and 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 concise sentences with no filler. The primary purpose is front-loaded, and the conditional behavior is stated efficiently without redundant 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?

For a simple, optional-parameter, read-only listing tool with no output schema, the description covers the behavior an agent needs to call it correctly. Nothing important 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 schema already documents the parameter. The description adds semantic meaning by explaining the effect of omitting versus providing input_format, which goes beyond a simple type/description.

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

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

The description clearly states the tool lists supported conversion formats and immediately distinguishes the two result modes based on the optional argument. This is specific enough to separate it from siblings like convert and list_options.

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 guidance on when to omit or provide input_format, which is the main choice an agent faces. It does not explicitly contrast against sibling alternatives, but the behavioral distinction is clear and sufficient for this simple tool.

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, so the description doesn't need to re-establish that this is a safe read. It adds useful return-content detail (exact names, types, and allowed values) and ordering guidance, but it does not go into deeper behavioral traits like error conditions or how format pairing affects results.

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 no wasted words: the first front-loads what the tool returns, and the second gives a crisp call-timing instruction. The examples make the purpose concrete without 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?

With a complete schema and no output schema, the description adequately covers what the tool returns (exact names, types, and allowed values) and how to use the result. The agent knows why, when, and how to invoke it.

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 both input_format and output_format already have descriptive text and examples. The description adds no new parameter-level constraints or syntax beyond restating that these refer to source and target formats.

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: it lists the settings a given conversion accepts, with concrete examples like resize, quality, codecs, bitrate, trim, and crop. This distinguishes it from sibling tools like convert (which performs conversion) and list_formats (which lists formats).

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 explicitly says to call this before convert whenever the user asks for anything beyond a plain format change, and to pass the returned options into convert. It gives clear timing and a condition, though it does not explicitly contrast itself with list_formats or state when not to call it.

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