qencode

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

Beyond annotations (readOnlyHint=false, idempotentHint=false), the description discloses key behavioral traits: asynchronous CDN provisioning causing delayed visibility, unstable `public` value immediately after creation, status values `created`/`exists`, and the `bucket_conflict` error for name collisions. This is exactly the kind of context that helps an agent anticipate side effects.

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 clear sections (usage rule, args, returns, async note, visibility caveat) and front-loads the main purpose. It is somewhat verbose, but every sentence carries useful information; no filler. A minor trim of the async details could improve conciseness, but it remains appropriately sized for the tool's complexity.

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 (async provisioning, idempotent no-op, naming validation, public flag instability), the description is complete. It explains return values, edge cases, and operational guidance (poll list_buckets, expect public flag flip). The output schema is also referenced with the return format, so the description fully covers what an agent needs.

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 provides only parameter names and types, with 0% coverage in the schema. The description compensates fully by specifying the name regex (lowercase letters/digits/hyphens, 6-63 chars), the allowed regions (us-west, eu-central), and the error behavior for invalid names. This is critical meaning 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?

The description opens with 'Create a new Qencode Media Storage bucket' — a specific verb and resource. It clearly differentiates from siblings by explicitly stating this tool is only for creating a bucket or long-term retention, not for default temp-storage scenarios, and references list_buckets as the tool to poll for confirmation.

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 and when-not-to-use guidance: 'Call this ONLY on an explicit request' and 'Do NOT call it just because a transcoding request lacks a destination'. It also names the alternative behavior (omit destination for 24-hour temp storage) and points to list_buckets for confirming creation.

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 discloses that the call is synchronous, blocking, size-capped, and limited to a ~10 minute presigned upload window, all valuable behavioral context. However, it contradicts the annotations: it states 'An existing object at this key is overwritten' while annotations mark `destructiveHint: false`. This is a direct conflict, so the score is 1.

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: a one-line summary, a paragraph on mechanics, an 'IMPORTANT' callout, and cleanly formatted Args and Returns. It is detailed but every sentence provides necessary caveats or context, making effective use of 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 description covers the tool's flow, constraints, parameters, return value, and alternatives. It even specifies the return shape `{bucket, key, size_bytes, status: 'uploaded'}` and edge cases like redirects and timeouts. With an output schema present, the textual return explanation is a bonus; the description leaves no major gaps.

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 provides only names/types with no descriptions, so the description carries the full burden. It adds rich semantics: `source_url` must be a publicly reachable http(s) URL and rejects non-http(s), private/loopback hosts, redirects, and 4xx/5xx; `key` explains destination path and overwrite behavior. This goes far beyond the schema's bare field names.

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+resource: 'Server-side copy of a public URL into a bucket (no transcoding).' This clearly identifies the primary action and differentiates it from transcoding tools. It also notes 'use this to ingest an existing asset into Qencode Media Storage as-is,' reinforcing its distinct purpose.

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 when to use this tool: 'use this to ingest an existing asset into Qencode Media Storage as-is.' It contrasts with transcoding: 'To store a *transcoded* result instead, set a `destination` on a transcoding job' and advises out-of-band uploads for very large sources: 'upload those out-of-band instead.' This is clear usage 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 mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: server-side fetch bypasses bot challenges, rejects binary media, truncates at ~5 MiB, and warns that result content is untrusted data. This goes well beyond annotation basics and preempts security pitfalls.

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?

Although long, the description is well-structured with clear sections (intro, usage, args, returns, security) and bullet lists. Every section adds necessary operational detail, and the front-loaded summary plus examples makes it easy to scan. No filler or 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?

The tool is complex due to Qencode's file-pointer architecture and diverse file types, but the description covers all key aspects: how to obtain the file URL, what output formats exist, the return dict fields, truncation behavior, and security implications. An output schema is present and the description appropriately complements it without repeating structured details.

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 fully compensates for the single `url` parameter: it requires an https:// URL, lists acceptable file extensions (`.json`, `.txt`, `.srt`, `.vtt`, `.xml`, `.m3u8`, `.mpd`), explicitly rejects binary media, and explains how to handle s3:// URLs via get_download_url. This is far more than the schema alone would convey.

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+resource: 'Fetch a completed job's result FILE and return its text/JSON inline.' It clearly distinguishes this tool from generic web-fetch and sibling tools like get_download_url by explaining its unique server-side fetch behavior and the file-oriented outputs it supports.

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 explicit when-to-use and when-not-to-use guidance: use instead of a generic web-fetch due to Qencode storage blocking clients, and use get_download_url for s3:// URLs or binary media. It also explains how to locate the URL from a completed job via texts[] and storage.names, giving concrete usage 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 readOnly, idempotent, non-destructive. The description adds valuable detail: the exact return structure (`uri`, `mime_type`, `content`) and the error handling for unknown URIs, including the `available_uris` fallback. This goes beyond the annotations without contradicting them.

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 a front-loaded main sentence, a brief context paragraph, and clearly labeled Args/Returns sections. Every sentence carries meaning — even the Claude Desktop note justifies the tool's existence. Nothing is redundant 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?

For a single-parameter read tool with a strong annotation set and an output schema, the description covers all necessary ground: what it does, what the argument looks like, what the response contains, and error behavior. It is complete enough for an agent to select and invoke it correctly without further clarification.

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?

Although the schema itself has zero description coverage, the Args section fully explains the `uri` parameter: it must be a `qencode://...` URI from a `search_qencode_docs` hit, with five concrete examples. This is exactly the kind of semantic enrichment the schema lacks, and it directly guides correct invocation.

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 'Read the full content of a Qencode knowledge-base resource by URI' — a specific verb and resource. It further distinguishes itself from siblings by noting it works for every URI returned by `search_qencode_docs` and that it's the tool-based counterpart to the MCP `resources/read` operation, removing any ambiguity.

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 ties usage to URIs from `search_qencode_docs`, provides multiple example URIs, and explains the rationale for its existence (clients that lack `resources/read`). It doesn't enumerate negative cases or alternative tools, but the context makes when-to-use 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?

The description goes well beyond the annotations by disclosing that the expires parameter is silently clamped to [300, 600] seconds, that unknown buckets fail with 'bucket_not_found,' and that the URL is always a presigned GET URL that stops working at expires_at even for public buckets. It also warns the user not to edit the signed URL, which is crucial operational guidance.

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 into an Args list and a Returns explanation. Every sentence contributes essential information, such as clamping, public flag behavior, the signature caveat, and the re-issue strategy. It is thorough without being padded.

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 the return shape, failure modes, edge cases (clamping, public buckets), and usage advice. Combined with the annotations, it provides a complete picture for a tool with 3 parameters, making it self-sufficient for correct invocation.

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

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

With 0% schema description coverage, the Arg block carries the full burden and does so excellently: bucket is defined with a failure mode, key is shown with an example ('out/result.mp4'), and expires is explained with clamping behavior and a default. This adds meaning far beyond the raw schema fields.

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 first sentence, 'Return a time-limited download URL for an existing object,' uses a specific verb and resource while adding the critical qualifier 'time-limited.' This clearly distinguishes it from siblings like list_objects and fetch_job_result, 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 description provides clear context: it is for obtaining a presigned URL that expires, and advises re-issuing the call when a lasting URL is needed. It also notes the URL works regardless of the bucket's public flag, which helps decide when to use it. However, it does not explicitly name alternative tools for downloading/copying objects, so it stops short of a full when-not-to-use comparison.

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 read-only, idempotent, and non-destructive behavior. The description adds no additional behavioral context, such as how status might change over time, whether it's a lightweight check, or any limitations. It simply restates the function without enhancing the agent's understanding.

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, concise sentence with no unnecessary words. It is appropriately brief for a simple status-checking tool, though it lacks the additional context that would make it more valuable.

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 definition exists within a broader set of related tools, but the description fails to clarify its role relative to siblings like 'get_job_status_detailed' or 'fetch_job_result'. It doesn't mention that a detailed version exists or suggest next steps, making the context incomplete despite the presence of an output schema.

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 contains one required parameter, task_token, with no description in the schema or the tool description. Schema description coverage is 0%, and the description does not compensate by explaining how to obtain or use the token. The parameter name is self-explanatory but not sufficient for correct invocation.

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's function using a specific verb ('Fetch') and resource ('current status of a transcoding job'). However, it doesn't differentiate from the sibling tool 'get_job_status_detailed', so it's not fully distinguished.

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 no guidance on when to use this tool versus alternatives like 'get_job_status_detailed' or 'wait_for_job'. There is no mention of prerequisites, exclusions, or recommended scenarios, leaving the agent without selection 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 signal readOnly/idempotent/non-destructive, but the description adds substantial context: the two-step flow (compact status first, then master status_url), the SSRF host check, and the 'never errors where get_job_status would have succeeded' guarantee. This goes well beyond annotation basics.

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 with the core purpose, then uses short paragraphs for comparison, usage, and flow. Every sentence adds valuable information without redundancy or fluff. Well-structured for quick 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?

Includes important edge cases (no status_url yet, SSRF failure), how it differs from get_job_status, and when to call it relative to wait_for_job. With an output schema present, return details are already covered, so the description covers everything else needed for correct tool selection and invocation.

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

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

Schema coverage is 0% and the description does not mention task_token at all. The parameter name is self-explanatory (a token identifying the job), but the description provides no guidance on how to obtain it or any format expectations, so it fails to compensate for the low 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?

Description opens with 'Fetch the full, authoritative status of a transcoding job' — a specific verb and resource. It explicitly contrasts with get_job_status by focusing on per-rendition details via status_url, clearly differentiating the tool from its 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?

Provides explicit when-to-use advice: 'Use this once a job is finishing/finished (e.g. after wait_for_job returns completed) when you need the concrete output artefacts rather than just the overall status/percent.' Also names the alternative (get_job_status) and describes the fallback behavior, making the choice unambiguous.

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?

Goes beyond annotations by detailing the return shape (buckets array with name, region, created_at, public), explaining the public flag's meaning and eventual consistency after bucket creation, and clarifying account-level sharing. This is valuable context that annotations alone do not 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 well-structured and front-loaded: it states the action first, then explains fields, provides a caveat, and ends with an account-level note. Every sentence earns its place 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?

For a simple read-only list tool with no parameters and an output schema, the description is fully complete. It covers return fields, the public flag's semantics, the eventual consistency caveat, and account-level behavior, leaving no significant gaps.

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 the baseline is 4. The description correctly mentions no parameters, and the input schema confirms this, so no additional parameter explanation is needed.

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 the Qencode Media Storage buckets for the account, using a specific verb and resource. It distinguishes this from siblings like list_objects by noting buckets are account-level and not per-project, making the 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?

Provides clear context for usage: buckets are account-level, visibility is managed in the portal (not via these tools), and warns not to cache the public flag after create_bucket. It implies when to use this list operation and gives a caveat about eventual consistency, though it does not explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat safety. It adds valuable behavioral details beyond annotations: unknown bucket fails with 'bucket_not_found', one call returns up to ~1000 objects, and the response shape with is_truncated/next_token. This discloses error conditions and pagination behavior, enriching the agent's understanding.

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 Args and Returns sections. It front-loads the purpose in one sentence, then methodically covers each parameter and return behavior. No wasted words; every sentence provides necessary information for correct invocation and pagination handling.

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 moderate complexity (3 params, pagination, error cases), the description is complete. It includes return shape, pagination mechanics, error behavior, and bucket discovery via list_buckets. Even with an output schema present, the description adds crucial context about limits and failure modes, making it fully sufficient for an agent to use the tool 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?

With schema description coverage at 0%, the description fully compensates. Each parameter is explained with purpose and example: bucket (with error behavior), prefix (e.g. 'raw/'), and continuation_token (how to use next_token). It also documents the response structure and pagination limit, giving complete semantic 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 description clearly states the tool's function: 'Browse the contents of a Qencode Media Storage bucket.' It identifies the resource (bucket objects) and specific actions (listing with prefix filtering and pagination). This distinguishes it from siblings like list_buckets, which lists buckets rather than their contents.

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 clear contextual guidance: references list_buckets for bucket names, explains prefix filtering with an example, and details pagination using continuation_token. It does not explicitly name alternatives or exclusions, but the cross-reference and pagination instructions convey when and how to use the tool. A minor gap is the lack of an explicit 'use this instead of X' statement.

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

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

The description adds substantial behavior beyond the annotations: it discloses that the tool resolves a license key, renders in a sandboxed iframe, rejects presigned manifests due to segment 403s, applies client-specific CSP origin policies, may return a client_note, and refuses DRM/signed-cookie playback. This is rich, non-contradictory context that the annotations alone do not 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 tightly organized: a purpose statement, usage context, parameter list, policy explanation, rejection handling, client_note behavior, and limitations. Every sentence adds operational value, and the most important usage guidance appears early. The length is justified by the tool's complexity.

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 description is remarkably complete: it covers source types, URL requirements, rejection scenarios, client-specific behavior, user communication obligations, and unsupported playback modes. The presence of an output schema means return-value documentation is not required from the description, and this description leaves no obvious operational 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 0%, so the description carries the full burden for parameter meaning. It explains source_url with format and presigned-manifest caveat, poster_url as an optional pre-play image, source_type with concrete MIME examples, and title as a display label. This fully compensates for the empty schema descriptions.

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: 'Open an inline Qencode video player in the chat for a playback URL.' It clearly distinguishes this tool from siblings by framing it as the playback/UI action, not a fetch, transcode, or download operation, and explicitly ties it to post-job completion.

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 after a job completes'), names the source of the playback URL ('from get_job_status_detailed'), and provides concrete alternatives and exclusions: build a public Media Storage URL instead of calling get_download_url, never refuse up front, and use create_bucket/download_url_to_bucket for external-origin videos on strict clients. It also states unsupported cases (signed-cookie/DRM).

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, destructiveHint=false. The description adds behavioral context about returning a ranked list of URIs with summaries, and the 'call this first' heuristic. It does not contradict annotations and provides useful workflow insight beyond the defined hints.

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: a concise opening sentence, return format, usage trigger, parameter details, and return explanation. Every sentence adds value, with no fluff. The use of a bulleted Args section and explicit examples makes it efficient to parse.

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 fully covers the tool's purpose, input parameters, return format, and next actions. It integrates with the existing MCP ecosystem (fetch_qencode_doc) and explains the workflow. The output schema is complemented by the explicit return structure ('A dict with hits...'), making it complete for an agent to invoke 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 0%, but the description fully compensates. It explains 'query' as free-text search with concrete examples ('hls widevine ezdrm', 'thumbnail sprite') and 'limit' with its default value (8). This adds substantial meaning beyond the raw schema.

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

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

The description states a specific verb ('Search') and resource ('Qencode knowledge base (recipes + reference docs)'). It clearly distinguishes itself from siblings by positioning it as the first step for recipe discovery, contrasting with fetch_qencode_doc for reading full content.

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 guidance is given: 'Call this first whenever you're unsure which recipe applies.' It also directs users to fetch_qencode_doc for reading full content and notes the alternative resources/read path, providing clear when-to-use and when-to-use-other-tool 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 indicate mutability (readOnlyHint=false) and non-idempotency. The description adds significant behavioral context: it catches common composition mistakes upfront, the underlying client auto-wraps the query, and it explicitly states that stitching and source are mutually exclusive. It also clarifies that encoder_version is not auto-injected, which is a key behavioral trait 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?

While well-structured with sections and examples, the description is quite verbose. It contains multiple paragraphs, lists, and three full examples. Some sentences could be trimmed or combined without losing meaning. For a tool description, conciseness is valued, and this one, though thorough, does not tightly earn every sentence.

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 (2 parameters, nested objects, many edge cases like stitching, DRM, ABR, etc.), the description is remarkably complete. It covers the query shape, common mistakes, encoder version guidance, examples for different scenarios, and usage of sibling docs. The output schema exists, so return values need not be explained. No gaps remain for typical use cases.

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 carries the full burden for parameter semantics. It explains the `query` parameter in great detail, including required shape, common mistakes, and examples for vmaf, video_intelligence, and stitching. The `payload` parameter is not mentioned, but it is optional with a default null. Overall, the description adds substantial 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 description clearly states the tool's purpose: 'Submit a job with the raw `query` JSON.' It distinguishes itself from the sibling `transcode_video` by noting that this tool does not auto-inject `encoder_version`, making the specific verb+resource+scope clear.

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 explicit guidance on when to use this tool versus alternatives. It compares with `transcode_video`, advises calling `search_qencode_docs` and `fetch_qencode_doc` for complex queries, and specifies encoder version selection (1 for VMAF/stitching, 2 for v2 outputs). It also lists common mistakes to avoid, giving clear usage boundaries.

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 provide minimal behavioral hints (openWorldHint true), but the description compensates extensively: it details encoder_version auto-injection, common composition mistakes, output-specific requirements (e.g., stream[] for ABR, vmaf needs distorted URL), and references to parameter defaults. No contradiction with annotations exists.

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 well-structured: it begins with a clear purpose, then lists parameters with detailed explanations and multiple examples. Each section earns its place given the tool's complexity. Could be more tightly edited (e.g., combining some examples), but overall it is front-loaded and logically organized.

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 high complexity (many output formats, nested arrays, auto-injected fields), the description covers all essential aspects: source, outputs, payload, encoder_version, unsupported stitch jobs, and dependencies on recipe documents. The presence of an output schema means return values do not need description. No gaps observed.

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 input schema has 0% description coverage, leaving all meaning to the free-text. The description thoroughly explains the `source` URL formats, the complex `outputs` array format with numerous examples and pitfalls, and the optional `payload`. It adds critical context like the naming convention (`output` not `format`), stream[] placement, and per-output-type required fields, far exceeding what the schema alone provides.

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

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

The description clearly states 'Submit a transcoding job' as the tool's purpose, specifies various output formats (mp4, webm, advanced_hls, etc.), and explicitly distinguishes from sibling tool `start_encode2_raw` by noting stitch jobs are not supported here. This provides a specific verb+resource with clear differentiation among siblings.

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

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

The description provides strong guidance on when to use this tool (for standard transcoding jobs) and explicitly directs stitch jobs to `start_encode2_raw`. It also instructs to consult recipes via `search_qencode_docs` and `fetch_qencode_doc` before submitting, covering prerequisites. However, it does not address when to use `transcode_video` versus other sibling like `wait_for_job` (which is obviously a polling tool), so it lacks some contextual exclusion.

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, destructiveHint false. Description adds detailed behavioral traits: three exit conditions, priority order, MCP10 cap guarding against malicious timeouts, and returns last observed status. No contradictions.

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?

Description is well-structured, front-loaded with purpose, and every sentence (including the cap explanation) adds value. Appropriate 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?

For a polling tool with good annotations and an output schema, description covers exit conditions, priority, cap, and return behavior enough. Output schema covers return value details.

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 description must compensate. It provides meaning for timeout_seconds (deadline derived from it) and poll_interval (can be clamped down), but does not explicitly define task_token or units/defaults for poll_interval. Partially compensates.

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?

Description states 'Poll a transcoding job until it reaches a terminal state or times out,' a specific verb+resource with clear scope. It differentiates from siblings like get_job_status by emphasizing polling/waiting.

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?

Description implies usage context: block until job completes or timeout. It does not explicitly name alternative tools or exclusions, but the polling semantics are clear. Lacks explicit 'use when' guidance.

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