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

Annotations cover the safety profile (not read-only, open-world, non-idempotent, non-destructive), and the description adds account/quota context ('Runs against your account and counts toward your quota'), which is real value beyond structured fields. It does not say whether conversion is synchronous or must be polled via the sibling get_job, which is a notable omission for this kind of 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?

Three tight sentences, front-loaded with what it does and what it returns, followed by input selection and the list_options prerequisite. No filler sentences and no repetition of the name or 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 six-parameter tool with no output schema, it covers the return value (download link), auth/quota impact, and the key input decision. The remaining gap is the processing model — nothing says whether the result is immediate or requires polling get_job, which matters given that sibling exists.

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 goes further by explaining the trade-off between source_url and import_id and their origin (create_upload), and by warning that option names differ per conversion and must come from list_options rather than being guessed.

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 ('Convert a file to another format') plus the outcome ('return a download link'). It also distinguishes its inputs from the sibling create_upload and points to list_options, so an agent can place it among siblings 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?

Explicitly routes the agent: use source_url when the file is already reachable, use import_id for a file on a device, and call list_options first to get exact option names. Both branches and the prerequisite call are stated, not implied.

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

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

Annotations declare a non-idempotent, non-destructive write, and the description adds genuinely useful behavior beyond that: it returns an import_id plus a PUT URL, the conversion starts automatically the moment bytes arrive, and the result is collected via a separate convert call that blocks until the file lands. That is meaningful workflow context not available in the annotations.

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

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

Front-loads the core decision rule before the mechanics, and the return/completion workflow is packed efficiently into two sentences. The opening 'Get somewhere to put a local file' is slightly informal but not wasteful.

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

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

With no output schema, the description correctly discloses the return shape (import_id + PUT URL) and the required follow-up call, which is the key information an agent needs. A brief note on upload lifetime or size limits would close the 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 description coverage is 100% and each of the three parameters is already documented in the schema. The description restates output_format's role ('what the file should become') and reinforces the auto-start behavior, but adds no syntax, format list, or constraint detail beyond the schema baseline.

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 (create an upload destination for a local file) and immediately delineates scope: 'the right choice for ANY file that is not already at a URL.' An agent can distinguish this from the URL-based path 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 a decisive when-to-use rule ('any file not already at a URL, whatever its size') and a follow-up workflow step ('call convert with the import_id to collect the result'). It does not name the specific sibling tool used for the already-at-a-URL case, so routing to that alternative is 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one behavioral detail, that the download link is only present 'if finished', which signals a conditional response, but it says nothing about rate limits, polling expectations, or how long job state is retained.

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 zero filler; the conditional payoff (download link if finished) is packed into the same clause rather than 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?

There is no output schema, so the description must carry the return-value burden, and it only partially does: it mentions status and the finished-state download link but not the possible status values, the failure case, or whether the job_id expires. Adequate for a simple lookup but leaves meaningful gaps for a polling workflow.

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 one parameter at 100% schema description coverage, the schema already explains that job_id comes from convert, and the description adds no further semantics such as format, expiration, or invalid-id behavior. Baseline 3 is appropriate when the schema carries the meaning.

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

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

Specific verb+resource ('get the status of a conversion job') that clearly distinguishes it from siblings like convert and create_upload, and it adds what the caller actually receives (the download link). It stops short of naming a sibling or stating the lifecycle relationship to convert, so it stays at 4 rather than 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?

No when-to-use guidance appears in the description; the only hint that this follows convert lives in the schema's job_id description ('returned by convert'). There is no mention of polling, retry, or terminal-state conditions under which an agent should or should not call 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the result set varies by argument, but says nothing about ordering, pagination, or result size, so it adds only modest behavioral value beyond the 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 no filler; the primary action is front-loaded and the argument-dependent behavior follows immediately. 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 a simple, single-optional-parameter, read-only enumeration tool with no output schema, the description covers both invocation modes adequately. It does not describe the shape or ordering of the returned format list, a minor gap given the tool's simplicity.

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 single optional parameter is fully documented there, including an example ('pdf') and the omit-to-list-all semantics. The description essentially restates that same guidance, so it earns the baseline 3 without adding 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?

States a specific verb and resource ('List supported conversion formats') and clarifies its dual-mode behavior based on whether an argument is supplied. It does not, however, differentiate itself from the sibling 'list_options', whose scope could plausibly overlap with 'formats', leaving some ambiguity an agent must resolve.

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 conditional guidance: call with no argument to enumerate all input formats, or with input_format to discover valid conversion targets. There is no explicit when-not-to-use or pointer to the sibling 'convert', but the context is unambiguous for this read-only lookup.

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. The description adds the otherwise-undocumented return contract — exact names, types, and allowed values — which is genuinely useful behavioral context. It stops short of any richness about ordering or error behavior, so not 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?

Two sentences, zero filler, and front-loaded with what is returned before the routing instruction. 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?

There is no output schema, but the description compensates by stating what the return contains (setting names, types, allowed values), which is the key payload detail for this read tool. Combined with the convert-integration instruction, an agent has enough to call and use it correctly; only edge cases like unknown formats are unaddressed.

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 both params (input_format, output_format) are documented in the schema, so the baseline of 3 applies. The description only alludes to 'a given conversion' and does not add format-syntax or pairing guidance 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?

States a specific verb (List) and resource (settings a given conversion accepts) and enumerates what those settings cover: resize, quality, codecs, bitrate, trim, crop. It is clearly distinguishable from the sibling list_formats, which the description implies by scoping to conversion *options* rather than 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?

Gives an explicit trigger ('whenever the user asks for anything beyond a plain format change') and an explicit downstream action ('pass what it returns in the convert tool's options object'). It also names the alternative condition — a plain format change does not require this call — so the agent knows both when and 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.