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

Discloses async provisioning, unstable public value, and that it does not make the bucket public, going 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?

Concise but detailed, with clear sections; front-loads purpose and call guidance, then args/returns, then additional notes.

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?

Complete for the complexity: covers call conditions, arg constraints, return statuses, async behavior, polling, and portal visibility.

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?

Adds constraints on name (regex, lowercase, digits, hyphens) and region (us-west, eu-central), plus validation outcome 'invalid_bucket_name'.

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 'Create' with resource 'Qencode Media Storage bucket' and distinguishes from siblings by explicitly saying when NOT to call (e.g., 'Do NOT call it just because a transcoding request lacks a destination').

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 call ONLY on explicit request to create or keep long-term, and provides alternative behavior (omit destination, disclose) and suggests polling list_buckets to confirm.

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 key behaviors beyond the annotations: it is synchronous and blocking, has a ~10 minute presigned upload window, size caps, and overwrites existing objects ('An existing object at this key is overwritten'). It also details failure conditions for source URLs (non-http(s), private hosts, redirects, 4xx/5xx). These transparently state side effects and constraints, with no contradiction to the annotations (readOnlyHint=false, destructiveHint=false).

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 introductory statement, a clear paragraph on synchronous behavior and limitations, individual parameter details, and a return type specification. Each sentence adds essential information without redundancy. The formatting with section breaks improves scannability while remaining appropriately detailed.

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 covers all necessary aspects: what it does, when to use it vs alternatives, parameter semantics, synchronous vs asynchronous behavior, failure modes, overwrite semantics, and the return value structure. The included return schema `{bucket, key, size_bytes, status: "uploaded"}` is sufficient. Nothing critical is omitted for an agent to decide and correctly invoke this tool.

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 input schema has no descriptions (0% coverage), the tool description fully explains all three parameters: source_url includes requirements (publicly reachable http(s), no private hosts, redirects fail), bucket is the destination name, and key includes overwrite behavior. This provides complete semantic meaning beyond the bare schema property 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 clearly states the action: 'Server-side copy of a public URL into a bucket (no transcoding).' It explicitly distinguishes this from transcoding jobs, and the title 'Fetch URL into bucket' reinforces the purpose. The verb 'copy' and resource 'bucket' are specific, and the no-transcoding note differentiates it from sibling tools like transcode_video.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'use this to ingest an existing asset into Qencode Media Storage as-is. To store a *transcoded* result instead, set a `destination` on a transcoding job.' It also advises against using this for large files and suggests out-of-band uploads, giving clear criteria for selection among sibling 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 carry readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact return structure (uri, mime_type, content) and, notably, the error behavior on unknown URIs (returns error dict with available_uris). This is meaningful disclosure of failure semantics that the annotations 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?

Well-structured with a front-loaded purpose sentence followed by scope, Args with examples, and Returns with error behavior. It runs a bit long, but every section earns its place — the URI examples and error-handling detail are high-value for a reader. Slightly verbose but justified.

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?

Complete for a single-parameter read tool: purpose, scope, usage routing, parameter semantics with examples, return format, and error behavior are all covered. Output schema exists and annotations carry the safety profile, so nothing an agent needs to call 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 coverage is 0% — the schema declares only a bare string named 'uri' with no description. The description fully compensates by explaining the value is a qencode:// URI from search_qencode_docs and supplying five concrete examples across recipe, docs, and schema namespaces. For a single parameter this is complete, actionable documentation.

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 ('Read') and resource ('Qencode knowledge-base resource by URI'), and explicitly ties its scope to URIs returned by search_qencode_docs, distinguishing it from the transcode/storage siblings. It even positions itself as the tool-based counterpart to resources/read, which clarifies its role versus other read mechanisms.

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

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

It gives clear context on when to use it: with any URI produced by search_qencode_docs, and explains it exists because some clients don't expose resources/read. It lacks explicit when-not-to-use or alternative exclusions beyond the implicit contrast with search (which produces, not reads), so it stops short of a 5.

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 thoroughly discloses behavior: time-limited URL, clamping of expires, behavior regardless of bucket public flag, non-permanence, and the need to pass the signed URL unchanged. This goes beyond the readOnly/idempotent 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 longer than strictly necessary but every sentence adds relevant context, such as clamping, public-flag independence, and signature handling. It is well-structured and not 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?

The description covers the return shape, failure mode for unknown buckets, expiration semantics, clamping, and user-handling instructions. It is fully sufficient for an agent to invoke the tool correctly without additional context.

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?

Even though the schema lacks descriptions, the tool description fully explains bucket, key, and expires, including the default and clamping behavior. All three parameters are meaningfully covered.

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 returns a time-limited download URL for an existing object, using a specific verb and resource. It is easily distinguished from sibling tools like download_url_to_bucket and list_objects.

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 useful usage guidance, such as re-issuing the call for a lasting URL and handing the URL verbatim, but it does not explicitly contrast this tool with sibling alternatives like download_url_to_bucket. The when-to-use context is partially implicit.

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

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

The description matches the readOnly and idempotent annotations and does not claim side effects. It adds no extra behavioral detail beyond what the annotations already convey, so a mid-level score 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?

The description is a single clear sentence with no unnecessary words or redundant details.

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

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

The basic operation is understandable and an output schema exists, so return values need not be described. However, the description omits guidance on choosing among related status/wait tools and leaves the token parameter unexplained.

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 single required parameter task_token is only named in the schema with no description. The description does not explain where the token comes from or how to format it, leaving low parameter coverage uncompensated.

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

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

The description clearly states a specific operation: fetching current status of a transcoding job. It does not explicitly differentiate from the sibling get_job_status_detailed tool, so it loses the top score.

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

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

The phrase 'current status' implies an immediate non-waiting fetch, but there is no explicit guidance about when to prefer this over get_job_status_detailed or wait_for_job, nor any exclusions.

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 readOnly and idempotent, but the description adds meaningful behavior: it explains the flow of querying the compact /v1/status first, following status_url if safe, and falling back to compact status when unavailable or unsafe. It also guarantees it never errors where get_job_status would succeed, which is valuable operational context beyond the annotations.

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

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

The description is well-structured into three short paragraphs: purpose, usage timing, and flow. Each sentence adds distinct value, and there is no fluff or redundancy. It is detailed yet concise.

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 what the tool does, when to use it, how it operates internally, and its failure-safe behavior. It gives enough context for an agent to decide and invoke it correctly without needing to see the output schema, which is reported to exist.

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 only parameter, task_token, is not explicitly described in the text and schema coverage is 0%. However, the token's purpose is self-evident from the tool name and the description's mention of a 'job.' The description indirectly implies it identifies the job to fetch status for, so it compensates adequately for the simple parameter.

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 purpose: 'Fetch the full, authoritative status of a transcoding job.' It also explicitly distinguishes from the sibling get_job_status by noting it follows the status_url for complete detail, making it unique among the provided 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 explicit usage direction: '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.' This tells when to choose it over alternative status 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?

The annotations already declare readOnlyHint and idempotentHint, and the description adds valuable detail about the returned fields and the transient nature of the 'public' flag. No contradictions or hidden side effects are present.

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 with the core purpose. Each paragraph adds relevant information—return format, field semantics, and an important caveat—without unnecessary repetition.

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

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

Despite having no parameters, the description fully covers the tool's behavior, output fields, and important operational caveats. It even points to additional documentation for polling guidance, making it self-sufficient for an agent.

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 and the schema coverage is 100%, so parameter semantics are trivially satisfied. The baseline score of 4 applies because no parameters exist to clarify.

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: listing Qencode Media Storage buckets available to the account. It also distinguishes this from per-project operations and explicitly notes the account-level scope.

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 practical usage guidance, including the caveat about eventual consistency of the 'public' flag after bucket creation. It does not explicitly compare to sibling tools like list_objects, but the purpose and scope are clear enough for appropriate 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds meaningful behavioral details: return structure ({objects, is_truncated}), pagination behavior (~1000 objects per call), and the bucket_not_found error. This goes beyond the annotations and helps an agent predict outcomes, though it could mention eventual consistency or ordering, but that's minor. Score 4.

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 compact and well-structured: a one-line purpose, parameter explanations, and return/pagination details. Every sentence adds value, and the pagination logic is explained clearly. It's appropriately sized for the tool's complexity. Score 5.

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 listing tool with an output schema and clear annotations, the description covers everything an agent needs: purpose, parameters, error handling, return format, and pagination. It even mentions the ~1000 object limit and how to page. There are no obvious missing details that would prevent correct invocation. Score 5.

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 full responsibility for parameter meaning. It thoroughly explains all three parameters: bucket (with reference to list_buckets and error behavior), prefix (with example 'raw/'), and continuation_token (tied to pagination). This far exceeds the bare schema and fully compensates for the coverage gap. Score 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?

States a clear verb ('Browse') and resource ('contents of a Qencode Media Storage bucket'), making the tool's purpose unambiguous. It doesn't explicitly name a sibling to differentiate, but the distinct resource (objects vs buckets) is obvious from the name and context. Slightly below 5 because it doesn't explicitly contrast with list_buckets or other alternatives.

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

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

Provides strong usage context: references list_buckets for bucket names, explains the prefix filtering, and details pagination with continuation_token and next_token. It also notes the error case for unknown buckets. It doesn't explicitly state when to avoid this tool, but the guidance is sufficient for correct invocation. A bit short of 5 because exclusions or alternative conditions aren't spelled out.

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 readOnly/idempotent/destructive annotations already cover safety expectations. The description adds useful behavioral detail by explaining that results are ranked and include URI, title, summary, and score.

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 purpose, usage, args, and return sections. It is slightly repetitive about calling fetch_qencode_doc in both the opening guidance and the returns section.

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 gives enough context for an agent to decide when to search, what parameters to pass, and how to consume the returned URIs. It also names the exact next tool for reading full content.

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?

Even though the JSON schema has no property descriptions, the description fully explains both parameters. It clarifies query as free-text with concrete examples and defines limit as max hits with a default.

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 searches the Qencode knowledge base, combining recipes and reference docs. It also distinguishes itself from the sibling fetch_qencode_doc by framing this as the search entry point.

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

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

It gives an explicit trigger: call this first whenever unsure which recipe applies. It also provides the follow-up action, directing the agent to fetch_qencode_doc for full content.

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 important behavioral details that go beyond annotations: it does not auto-inject encoder_version, v2 outputs require explicit setting, supported output formats and modes have constraints, and certain composition mistakes are validated up front. It also provides concrete examples showing expected query structure.

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 starts with a one-sentence summary, then explains query shapes, lists common mistakes, and gives two clear examples. Every section serves a concrete purpose, and the examples are directly actionable.

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 of raw transcoding queries, the description provides enough context to compose valid jobs, including version selection, format recipes, destination requirements, and links to documentation for more advanced cases. The output schema is present, so omitting return-value details is acceptable.

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 query parameter is documented extensively with shape, examples, required fields, and common pitfalls. The optional payload parameter is not explained at all, but it is optional and appears secondary to the core query workflow. Overall, the description compensates well for the absence of schema-level descriptions for the primary parameter.

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 that this tool submits a raw transcoding job with a raw query JSON, and explicitly contrasts it with transcode_video's auto-injection behavior. It also references relevant sibling tools for complex queries, making the tool's specific role 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?

The description provides explicit when-to-use guidance: use this tool for raw queries, set encoder_version manually, prefer transcode_video when auto-injection is desired, and consult docs via search_qencode_docs/fetch_qencode_doc for complex cases. It also notes duration checks and source URL requirements before submission.

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, the description discloses automatic encoder_version injection, vmaf auto-selection, and payload echo in callbacks. It also states unsupported stitch jobs. This adds meaningful behavioral context, though it doesn't discuss error handling or async behavior.

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 packed with essential information: examples, pitfalls, and special cases. Each line serves a purpose, and the structured layout with bullets and code blocks aids readability. Slightly verbose but justified.

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 open-world schema, the description covers required fields, provides examples, points to external docs, and explains edge cases like vmaf and video_intelligence. It supplies sufficient context for an agent to use the tool correctly without missing critical 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?

Since the schema has no descriptions, the tool description fully compensates: explains source URL formats, outputs structure with detailed examples and required fields for vmaf and video_intelligence, the common output/format mistake, and payload semantics. This is comprehensive.

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?

Clearly states 'Submit a transcoding job' with a specific verb and resource. Differentiates from sibling by explicitly noting stitch jobs are not supported and pointing to start_encode2_raw.

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 guidance on when to use this tool vs alternatives: states stitch jobs are not supported here and directs to start_encode2_raw with a recipe, and instructs to consult search_qencode_docs/fetch_qencode_doc before submitting. Also gives examples of valid outputs.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful details about blocking, timeout, poll interval, and the MCP10 cap, including the fallback of returning the last observed status. It does not overstate 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 numbered exit conditions and is appropriately detailed. It front-loads the main purpose and provides necessary edge-case behavior without unnecessary verbosity.

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 main behavior, exit conditions, and timeout/cap semantics. It does not detail the output schema, but it does mention returning the last observed status, which is sufficient given the input schema is fully specified and output schema may be standard for polling tools.

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 has no descriptions (0% coverage), so the description must compensate. It explicitly defines timeout_seconds as a wall-clock deadline and mentions poll_interval being clamped. task_token is not described but is inferable from the tool's purpose as the job identifier.

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 polls a transcoding job until terminal state or timeout, which is a specific verb-resource pair. It implicitly distinguishes from sibling tools like get_job_status by focusing on blocking/waiting behavior.

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 explains the polling behavior and exit conditions but does not explicitly mention when to prefer this over get_job_status or get_job_status_detailed. It gives implied usage (after starting a job) but lacks explicit alternatives.

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