qencode

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

Annotations already declare non-readOnly, non-destructive, idempotent, closed-world; the description goes well beyond by disclosing account-wide visibility to all projects, use of the caller's existing sign-in with no separate storage permission, conflict semantics (bucket_conflict creates nothing), and the exists/no-op path that never replaces an existing bucket.

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 critical do-not-provision guidance near the top, and every section carries operational weight (conflict behavior, return statuses, destination_prefix usage). It is longer than strictly necessary, particularly the duplicated name pattern and Args list mirroring the schema, but there is little pure 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?

Given a two-param mutation with annotations and an output schema, the description still usefully explains return fields (bucket, region, status, destination_prefix, conditional cdn_origin), the meaning of each status, and how to consume destination_prefix downstream. Nothing an agent needs to call or interpret this tool 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?

Schema coverage is 100% and both params have descriptions/enums, so the baseline is 3; the description adds real value with rejection error codes (invalid_bucket_name), a restated exact pattern, and the allowed region values in prose. It slightly duplicates the schema pattern rather than adding new syntax, keeping it at 4 rather than 5.

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+resource ("Create a bucket") and immediately bounds scope ("in the signed-in Qencode account"). It is clearly distinguishable from siblings like list_buckets, download_url_to_bucket, and transcode_video, and even describes what it does NOT create (no URL, no hostname, no third-party provider).

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 call condition ("ONLY on an explicit request to create a bucket or to keep a result long-term") plus an explicit anti-condition with the correct alternative (when a transcode lacks a destination, omit destination for 24-hour temp storage instead of provisioning a bucket). This is exactly the when/when-not/alternative structure that best guides agent selection.

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 (readOnlyHint=false, idempotentHint=false), the description thoroughly discloses blocking behavior, no progress token, the ~10-minute presigned window, server-side size cap, non-overwrite policy, SSRF rejections, redirect-not-followed behavior, and account-scope/security implications. It also exposes error statuses like 'bucket_not_found' and 'object_exists' so the agent can react 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 long but every sentence adds value. It is structured with a concise opening, an IMPORTANT callout, per-parameter explanations, a return-envelope section, and a SCOPE security section. The most critical constraint (synchronous, blocking) is front-loaded, and no filler or repetition exists.

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 tool's complexity, the lack of schema descriptions, and the presence of an output schema, the description covers all necessary context: input constraints, error statuses, recovery instructions, side effects, security implications, and success return shape. An agent possesses everything needed to invoke it correctly and safely.

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%, yet the description fully compensates. Each parameter gets precise semantics: source_url must be a public http(s) URL with private/loopback rejection and redirect handling; bucket must already exist and can be verified via list_buckets; key must be a new object key because existing keys are refused. This adds critical meaning beyond the bare 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 opening line states a specific verb and resource: 'Server-side copy of a public URL into a bucket (no transcoding).' It then explicitly contrasts with transcoding jobs ('To store a transcoded result instead, set a destination on a transcoding job'), which distinguishes it from the transcode_video sibling.

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 when-to-use guidance ('use this to ingest an existing asset into Qencode Media Storage as-is') and when-not-to ('very large or slow sources may time out — upload those out-of-band instead'). It also directs to alternative tooling via 'set a destination on a transcoding 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses a ~5 MiB read cap that sets truncated=true and omits result_json, the possibility of HTTP 403 from temporary-storage URLs, and a SECURITY warning that file content is untrusted data that may echo attacker text. This is unusually rich behavioral disclosure that the annotations do not carry.

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?

Information-dense and well front-loaded, with clear sections for purpose, URL derivation, args, returns, and security. It is on the long side and could tighten some prose, but nearly every sentence earns its place for a tool with non-obvious status-pointer semantics.

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?

Although an output schema exists, the description still documents the return dict (url, content_type, size_bytes, truncated, result_content, result_json) and the truncation edge case. Combined with the security note and URL-construction guidance, nothing an agent needs to call and interpret this tool 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?

Schema coverage is 0% and the single url parameter has no description, so the description must compensate—and it does extensively: https-only, accepted text/JSON extensions (.json, .txt, .srt, .vtt, .xml, .m3u8, .mpd), rejected binary types, and the s3:// handling path. It also explains how to derive the URL from texts[] in list_jobs/get_job_status/get_job_status_detailed.

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 ('Fetch a completed job's result FILE and return its text/JSON inline') and immediately enumerates which outputs write their deliverable to a file versus into job status. It clearly distinguishes itself from siblings like get_download_url and list_jobs. An agent can tell exactly what this tool does 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?

Explicit when-to-use is given ('When the job is Done, call this immediately'), and alternatives are named with the conditions that select them: binary media is rejected and 'hand those URLs to the user or use get_download_url instead,' and s3:// URLs require get_download_url(bucket, key) first. Nothing 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 already declare readOnly, idempotent, non-destructive, and non-open-world, so the safety profile is covered. The description adds real value beyond that by disclosing the success return shape and the failure behavior (unknown URI returns an error with an `available_uris` list), which is not 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-loaded with the core purpose in the first sentence, then usage, args, and returns in a scannable structure. The example list and Returns block are slightly verbose, though the examples do earn their place given the 0% schema coverage.

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 read tool with an output schema and rich annotations, this is complete: URI format, valid value sources, examples, and error recovery path are all present. Nothing an agent needs 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?

Schema description coverage is 0% for the single `uri` parameter, so the description carries the burden — and it does, giving the format, the source of the URI, and five concrete examples across resource types. This fully compensates for the empty 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 (Read) and resource (Qencode knowledge-base resource by URI), and immediately distinguishes itself from search_qencode_docs by positioning itself as the full-content fetch. An agent can tell it apart from the sibling search tool 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?

Explicitly says to call it after `search_qencode_docs` or with a known `qencode://...` URI, and enumerates the doc categories it covers (recipes, best practices, storage, gotchas, error codes, schema digest). The when-to-use and the relationship to the alternative search tool are both 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?

Annotations already establish readOnly, idempotent, and non-destructive hints, so the bar for extra value is higher. The description goes far beyond that by disclosing the error envelope behavior, silent clamping of expires, the fact that the URL always expires regardless of public flag, signature fragility, and the exactly suitable consumer (open_player for progressive files only). This is rich, non-obvious behavior an agent must know.

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?

Every sentence earns its place. The description opens with a clear one-line purpose, then structures Args, Returns, safe/invalid usage, and exclusions. Despite being long, the length is justified by the subtle failure modes (signature corruption, HLS/DASH misuse, permanent vs. temporary links) that would otherwise cause incorrect calls.

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?

The description covers inputs, output shape, error semantics, time expiration, safe downstream uses, and explicit exclusions. It identifies all relevant sibling relationships (list_buckets, list_objects, open_player, cdn_url, destination_url, fetch_job_result) and explains how the returned URL relates to each. Given the tool's complexity secret, this is 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 0%, so the description must carry the full meaning for bucket, key, and expires. It does: bucket errors are envelope-style, key errors include recovery instructions, and expires is clamped to [300, 600] rather than rejected. It also explains the `url` and `expires_at` output fields, adding meaning the bare schema cannot provide.

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 opening sentence says exactly what the tool does: 'Return a time-limited download URL for an existing object.' The description also names specific sibling alternatives like list_objects, cdn_url, and open_player, so the tool's role is clearly distinguished from related operations.

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 is exceptionally explicit about when to use this tool: download a private object or feed fetch_job_result, and when not to: encode inputs should use cdn_url/destination_url, and this URL must not be used for HLS/DASH. It also instructs the agent to call list_buckets or list_objects and retry with a valid name rather than retrying the same key, giving actionable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context (e.g., latency, staleness, or whether it blocks), but it does not contradict the annotations. Since the bar is lowered by annotations, a 3 is appropriate.

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 concise sentence that is front-loaded with the action and resource. There is no redundancy or 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?

The description is minimal and omits crucial context: the meaning of task_token and when to choose this tool over get_job_status_detailed or wait_for_job. Even with an output schema present, the lack of usage guidance and parameter explanation makes it incomplete.

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 compensate for the undocumented task_token parameter. It does not explain that task_token identifies the job, nor does it provide any semantic meaning. The agent is left to guess what this token refers to.

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 (fetch) and resource (status of a transcoding job), which distinguishes it from siblings like get_job_status_detailed and wait_for_job. The action and target are 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?

No guidance is given on when to use this tool versus alternatives. It doesn't mention that get_job_status_detailed provides more detail or that wait_for_job blocks until completion, leaving the agent without routing context.

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, idempotentHint, and destructiveHint, covering safety. The description goes further, disclosing the two-hop request flow, the SSRF host check, and the best-effort fallback that returns compact status on failures. This is valuable behavioral context 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?

The description is detailed and somewhat long, but every sentence adds value: purpose, usage, flow, and fallback. It is front-loaded with the core purpose and structured logically. The length is justified by the tool's two-hop complexity, though it could be tightened slightly.

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 complexity (multiple HTTP calls, fallback, SSRF check), the description covers all essential behavior: what is returned, when it falls back, and that only the detail set is at risk. An output schema exists (though not provided), so return values are presumed covered. Nothing critical is missing for an agent to call it 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?

The schema has one required parameter (task_token) with 0% description coverage. The description implies the token identifies the job via references to list_jobs and get_job_status, but never explicitly explains its purpose or how to obtain it. For a single self-named parameter this is acceptable but not fully compensated.

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 fetches the full, authoritative status of a transcoding job, explicitly contrasting it with the simpler get_job_status. It specifies the resource (job status) and the added value (per-rendition details, warnings), making its distinct purpose 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?

It explicitly tells the agent when to use this tool: once a job is finishing/finished and concrete output artifacts are needed, rather than just overall status. It also implies the alternative (get_job_status) for compact status and describes the fallback behavior, giving clear context for selection.

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 mark readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail beyond that: the public flag is read-only, the timing instability for new buckets, the instruction to copy exact strings rather than assemble hosts, the rejection of s3:// prefixes, and the account-wide visibility. These are not inferable from annotations and are crucial for correct use.

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 lengthy but every section earns its place: it covers output structure, field semantics, caveats, and scope. It is organized into clear paragraphs and front-loads the core purpose. While it could be tightened slightly, the density of critical information justifies the length.

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?

The tool has no parameters and a read-only operation, but the description fully covers the output schema meaning, edge cases (CDN provisioning lag), and account-scope implications. It even warns against common misuse (copying destination_url as dest, using s3:// scheme). For an agent to call this correctly and interpret results, 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 has zero parameters, so there is nothing to describe. The description correctly omits parameter details; the schema is empty. Per rubric, a baseline of 4 is appropriate when no parameters exist, and the description doesn't need to compensate for schema gaps.

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 precise verb-resource pair: 'List the Qencode Media Storage buckets available to the account.' It clearly distinguishes from siblings like list_objects (which lists objects within a bucket) and create_bucket (which creates a bucket). The scope is explicit: it lists all buckets for the account, not just the current project.

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 provides extensive usage context: it states the returned data fields, warns about not caching the public flag for just-created buckets, and explains the account-wide scope and lack of separate permissions. It does not explicitly name alternatives like 'use create_bucket to create' but the purpose is clear enough that an agent would not confuse it. The SCOPE section effectively tells when and how to use this tool in the broader storage context.

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, idempotent, and non-destructive behavior, and the description adds substantial behavioral context beyond them: the card refreshes itself while jobs are in flight, clicking a job ID copies the token, there is no account-wide history, and the next/client_note result fields prescribe follow-up actions in the same reply.

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 well-structured with front-loaded purpose and clear paragraphs, but it is wordy and repeats itself: the playable-URL-to-open_player instruction appears twice, and the next-field explanation partially restates earlier guidance. A tighter version would preserve all core information with less redundancy.

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 tool has one parameter, annotations, an output schema, and a rich sibling set, the description is complete. It covers token provenance, caps, refresh behavior, follow-up tool routing, and the no-history constraint, so an agent has everything it needs to invoke the tool correctly and handle 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?

Schema coverage is 0%, so the description must carry parameter meaning, and it does: it defines task_tokens as job IDs shown most recent first, capped at 20, and clarifies they come from transcode_video/start_encode2_raw or user-pasted tokens. It even warns against calling create_bucket to find jobs, which is valuable semantics not in 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 opens with a specific verb and resource: 'Show an inline card of transcoding jobs from this conversation.' It clearly distinguishes the tool from siblings like get_job_status and refresh_jobs by describing the MCP Apps UI widget, filters, expandable rows, and output URLs, so an agent can pick it correctly.

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 when-to-use guidance: user asks for jobs/dashboard/status of several jobs, or right after submitting a job with transcode_video/start_encode2_raw. It also names alternatives to avoid, such as dumping get_job_status JSON or looping status checks, and tells the agent to pass task_tokens from the conversation rather than inventing them.

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, idempotent, and non-destructive behavior; the description adds substantial context on top: `bucket_not_found` failures, pagination limits (~1000 objects), truncation semantics, and the distinction between public CDN URLs and private object URLs. This goes well beyond what the annotations provide.

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 long but densely informative: a one-line purpose, an Args section, and a Returns/usage section. Every sentence adds operational value, such as 'Copy those URLs; do not assemble them' and 'page with continuation_token=next_token when is_truncated is true'. The structure makes the information 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?

Given the tool's complexity and the lack of schema-level descriptions, the description is remarkably complete. It covers required input, return shape, pagination, error cases, bucket relationships, URL semantics, and playback behavior. Even with an output schema indicated, this description ensures an agent can call and interpret the tool correctly without further lookup.

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 carries the full burden for all three parameters. It explains `bucket` with error behavior, `prefix` with a concrete example (`raw/`), and `continuation_token` with its relationship to `next_token` from a truncated response. This gives the agent everything needed to populate the arguments correctly.

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 ('Browse the contents of a Qencode Media Storage bucket'), immediately making the tool's scope clear. It also differentiates from siblings by referencing `list_buckets` for bucket names and `get_download_url` for playback, so an agent can distinguish list operations from bucket-level or URL-generation tools.

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 practical when-to-use guidance: browse objects, filter by prefix, and page with `continuation_token`. It explicitly warns against calling `get_download_url` for HLS/DASH and explains that private progressive files use it, which routes the agent to the correct sibling 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 readOnly/idempotent/non-destructive, yet the description adds substantial behavior the annotations cannot carry: rejection rules (presigned manifests, .mov), the CSP/origin policy variance across clients, the private-vs-public URL routing, the client_note passthrough, and the DRM/signed-cookie limitation.

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 and organized into scannable blocks, but the presigned-manifest rejection is restated in the Args section after being fully explained above, and the error-remediation bullets are lengthy — dense and useful, yet slightly 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?

For a tool with rejection paths, client-dependent CSP behavior, and multi-step recovery flows, the description covers invocation, prerequisites, failure handling, and result handling (client_note). Return values are covered by the output schema, so nothing material 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 description coverage is 0% (bare titles only), so the description must carry the burden — and it does, documenting all four params in an Args block with accepted forms, constraints, and defaults for source_url, poster_url, source_type (with example MIME values), and title.

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 opening sentence names a specific verb and resource ('Open an inline Qencode video player in the chat') and immediately distinguishes this tool from siblings by stating it renders an MCP Apps UI component rather than pasting a 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?

Explicitly states when to call it ('when a job is already Done with a playable URL, call this in the same reply as list_jobs — do not only paste the link'), which URLs to pass and from which siblings (list_jobs, get_job_status_detailed, get_download_url, list_objects), and gives per-error remediation paths naming specific alternatives (submit output: mp4, create_bucket + download_url_to_bucket).

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, idempotentHint, and destructiveHint. The description adds the key behavioral trait that the tool does NOT render a UI and that its payload matches list_jobs, plus the polling interval. This goes beyond the annotations, providing essential context for an agent deciding whether to call 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?

The description is two short paragraphs plus an args line, front-loaded with the critical warning 'Do not call this from the agent.' It efficiently conveys the purpose, behavior, and parameter constraint without redundancy.

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, the description still covers the return payload equivalence to list_jobs, the non-UI nature, and the usage constraint. An agent has everything needed to know when to avoid this tool and what it 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 schema only defines task_tokens as an array of strings with no description. The description adds meaning by stating these are job IDs, to be provided most recent first, and capped at 20. This is crucial for correct usage.

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 ('Poll job rows for the jobs card') and explicitly distinguishes it from list_jobs by noting it does not render a widget. It also tells the agent not to call it, which clarifies its intended usage.

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 instructs agents not to call this tool ('Do not call this from the agent') and directs them to list_jobs for showing or refreshing the card. It also describes the internal polling cadence (every 5s), making usage 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds meaningful context beyond that: results are ranked, each hit carries a short summary, and the URI must be handed to fetch_qencode_doc to get full content. It does not add much about limits or failure modes, but the annotation bar is already met.

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 follow-up step; the Args/Returns block is structured and readable. It is slightly long, and the Returns paragraph partially duplicates the output schema, but every sentence still conveys actionable 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 two-parameter search tool with a rich output schema, the description covers purpose, when to call it, the routing to fetch_qencode_doc, param semantics, and result shape. Nothing an agent needs to invoke it correctly or act on the results 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 description coverage is 0%, so the description carries the full burden and does so: it explains that query is free-text covering output type, codec, DRM provider, or feature name, with four concrete example queries, and gives the semantics and default (8) of limit. This is much richer than the bare schema titles.

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 Qencode knowledge base (recipes + reference docs)') and clarifies the unit of return (MCP resource URIs). It is clearly distinguishable from the sibling fetch_qencode_doc, which is named as the follow-up 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?

Explicitly prescribes when to use it ('Call this first whenever you're unsure which recipe applies') and names the alternative plus the transition condition ('To read the full content of any URI returned here, call fetch_qencode_doc(uri) next'). Routing is fully specified with no inference required.

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 cover the safety profile (destructive=true, non-idempotent, open-world), and the description adds substantial behavior beyond that: up-front validation of common query mistakes, the auto-wrap behavior of the client, the payload-as-callback-tag semantics and its error-on-object behavior, and the encoder_version divergence from transcode_video. This is a lot of non-obvious operational 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?

The lead sentence is front-loaded and every block (validation gotchas, examples, stitching, tool routing) is substantive rather than filler. It is long, and the error-catalog section borders on exhaustive, but the density is largely justified for a tool with a free-form JSON payload and zero schema documentation.

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 values need not be explained, and the description still covers the full job lifecycle around submission. Given the nested free-form query, zero schema coverage, and destructive/non-idempotent annotations, this is about as complete as a definition can be.

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 0% and the schema is a bare `additionalProperties: true` object, so the description carries the full burden — and it does: it documents the required inner query shape, the wrapped-vs-unwrapped acceptance, and the `payload` parameter's type constraint, callback-tag purpose, and error behavior. Field-level composition rules for `output`/`format`/`stitch` are also spelled out.

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 ('Submit a job with the raw `query` JSON') and explicitly contrasts itself with the sibling `transcode_video`, noting it does not auto-inject `encoder_version`. An agent can distinguish it from sibling tools 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?

Provides explicit when-to-use routing ('For complex queries — ABR ladders, DRM, stitching, callbacks — call `search_qencode_docs(...)` then `fetch_qencode_doc(...)`'), encoder_version selection rules (2 for v2 outputs, 1 only for VMAF), and a prescribed post-submit workflow (list_jobs, open_player, fetch_job_result). It also names usage boundaries such as stitch vs. source mutual exclusivity.

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 mutation and non-idempotency, and the description adds genuinely non-obvious behavior beyond them: automatic encoder_version injection (2, or 1 when vmaf is present), rejection of s3:// sources because the API would demand credentials, HTTPS-only requirement for video_intelligence sources, per-output validation rejections (bare advanced_hls), and the string-only payload retry contract.

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 one-line purpose, then Args, then workflow. Given 0% schema coverage the bulk is largely justified, but the block is long and the critical post-call workflow guidance is buried at the very end rather than surfaced near the top.

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, and the description covers everything else an agent needs for a complex multi-format job submission: source rules, per-format composition, validation constraints, defaults, and the required follow-up calls.

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 carries the full burden and does so comprehensively: source URL schemes, the outer `format` vs inner `output` naming trap, per-output required fields, destination URL composition rules, and worked examples for vmaf/HLS/video_intelligence. It also clarifies payload is a string-only callback tag and that a JSON object returns an error asking for retry.

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+resource ('Submit a transcoding job') that names exactly what happens. It implicitly and explicitly distinguishes itself from siblings by naming start_encode2_raw as the route for stitch jobs, which is not supported here.

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 routing rules: stitch jobs go to start_encode2_raw, recipes should be fetched via search_qencode_docs/fetch_qencode_doc before composing, and it prescribes the exact post-submission follow-up (list_jobs with the task_token, then open_player or fetch_job_result). Both when-to-use and the alternative are 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that timeout_seconds and poll_interval are ignored, explains why they remain for backward compatibility, and reveals the host's ~60s abort limit. It also states that the tool does not block or poll, which is critical behavior 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?

The description is dense but every sentence carries weight: deprecation status, alternative tools, host constraints, and parameter handling. The most important fact ('does not wait') is front-loaded, and warnings are grouped logically without redundancy.

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 that this is a deprecated compatibility stub with an output schema, the description says everything an agent needs: why the tool exists, what it does not do, which alternatives to use, and how to treat its parameters. 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?

With 0% schema description coverage, the description compensates by explicitly stating that timeout_seconds and poll_interval are ignored and explaining their compatibility purpose. It also references task_token in context with list_jobs, though it does not elaborate on token format or validation, leaving minor room for interpretation.

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 upfront that the tool is deprecated and does not wait, making its current no-op compatibility role unmistakable. It also names the sibling tools that should be used instead, which clearly distinguishes it from list_jobs, get_job_status, and get_job_status_detailed.

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 routing guidance: use list_jobs to watch a job, get_job_status for a single snapshot, and get_job_status_detailed for output artifacts. It also warns against looping status checks and resubmitting, leaving no ambiguity about when and how this tool should be bypassed.

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