Botverse

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

Even with annotations declaring readOnlyHint=false and idempotentHint=true, the description adds critical behavioral details: queued/dispatched steps are marked CANCELLED, completed steps are not reversed, and billing only applies to completed steps. This goes beyond the annotations and gives agents clear expectations about 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 three sentences, each contributing essential information: what the tool does, the effect on steps, and the billing implication. It is front-loaded with the action and contains no redundant or filler content.

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 simple (one parameter, output schema present, annotations provided), and the description covers the main behavioral facets including billing and non-reversal of completed steps. It does not explicitly address the behavior when the workflow is already completed or not in-progress, but the idempotentHint annotation mitigates this concern, making the description nearly 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?

The schema already provides 100% coverage for the single required parameter with the description 'Workflow ID to cancel.' The tool description does not add additional parameter-level detail, which is acceptable since the schema is sufficient. Baseline of 3 is appropriate.

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 'Cancel an in-progress workflow,' which uses a specific verb and resource, clearly distinguishing this from sibling tools like submit_workflow or get_workflow_status. It also describes the effect on queued/dispatched steps, making the tool's 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?

The description implies when to use this tool (when you need to stop an in-progress workflow) but does not explicitly state alternatives or when not to use it. The billing note and step-marking behavior provide context for deciding if cancellation is appropriate, but no direct sibling comparisons are made.

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 the asynchronous job lifecycle: 'Returns a job_id immediately. Poll get_job_status until complete, then get_download_url.' It also explains side effects of each conform method, such as duration changes or audio time-stretching for speed_conform, and details error semantics and fallback behavior. This goes well beyond the sparse annotations and does not contradict 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 long but front-loaded with the core purpose and method breakdown. Each section—method options, duration_policy, job flow, reliability—earns its place. The reliability/fallback paragraph is somewhat tangential but still useful for an agent to avoid wasted work. It is structured enough to remain navigable despite its 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 complex tool with nested options, asynchronous behavior, and multiple conform methods, the description covers everything needed to call it correctly: inputs, method selection criteria, output handling, and failure recovery. The output schema exists, so return values need not be spelled out, and the description does not leave critical 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?

Schema description coverage is 75%, and the description adds meaningful semantics on top: what each method does behaviorally, why target_framerate is required, and the exact effect of duration_policy. It does not elaborate on width, height, bitrate, or output_format, but the schema already documents those clearly. The added value is concentrated on the most important parameters.

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 leads with a specific action and resource: 'Mux a separate video file and audio file (both public HTTPS URLs) into one fresh-encoded output.' It clearly identifies the conform step (combining and reconciling two sources) and differentiates from sibling tools like transcode/convert by requiring two distinct input URLs. The title and description together leave no doubt about what the tool does.

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 selection guidance among the methods: 'use this when the rates already match' for mux, and concrete conditions for resample_video, interpolate_video, and speed_conform. It also explains duration_policy choices. It does not explicitly name sibling tools as alternatives (e.g., conform_media vs conform_from_url), but the two-URL requirement strongly implies the right use case.

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 readOnlyHint=false and idempotentHint=false, so the mutation/asynchronous nature is implied. The description adds significant value: it tells the agent to poll get_job_status until 'complete', describes the error shapes (structured errors from Botverse vs. bare HTTP 500 from MCP connector), and explicitly warns against writing fallback code, which is critical non-obvious 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 front-loaded with the core purpose and workflow, then adds a reliability/fallback section. It is longer than typical but the fallback guidance is high-value and earns its place. Slightly verbose but well-structured with clear sections.

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 an asynchronous transcoding tool with 4 params, output schema, and strong annotations, the description covers the full invocation lifecycle, error semantics, and fallback behavior. It also disambiguates from conform_from_url. 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 description coverage is 100%, so the schema already documents all 4 parameters. The description clarifies that video_object_key and audio_object_key are from get_upload_url, and that options matches conform_from_url's options object. This adds some context but doesn't go beyond what the schema plus sibling naming already 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 states a specific verb (Mux), resource (already-uploaded video and audio file from get_upload_url), and outcome (fresh-encoded output). It distinguishes itself from conform_from_url by clarifying local files or files too large to fetch by URL, which is critical for sibling differentiation.

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 use this for local files or files too large to fetch by URL, and references conform_from_url as the alternative. It also provides a clear workflow (poll get_job_status, then get_download_url) and a detailed fallback path with concrete CLI examples. This is strong 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?

The description adds substantial behavioral context beyond the annotations: fresh encoding, letterboxing rather than stretching, synthesized silent audio tracks, resolution/framerate defaults from the first video segment, immediate job_id return, and the polling workflow. It also gives error-handling guidance for distinguishing Botverse errors from MCP connector failures. There is no contradiction with 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 long but highly information-dense and organized: core behavior first, then use-case patterns, constraints, output behavior, async workflow, and reliability/fallback. The reliability paragraph is verbose with CLI examples, but still earns its place for preventing wasted retry/workaround efforts. Slight over-length keeps it from a 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 tool with nested arrays, ordered segments, mixed media types, async job returns, and multiple output formats, the description is complete. It covers input constraints, segment behavior, output format options, default resolution/framerate behavior, audio handling, job polling, download flow, and error fallbacks. The presence of an output schema means return-value detail is not required, and nothing significant 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 67%, and the description compensates richly: it explains segment type semantics, duration_seconds being required for images and ignored for videos, the ordered array behavior, minimum/maximum segment counts, the at-least-one-video rule, and how options default to the first video segment's resolution and framerate. These are critical semantic details not fully carried by the schema alone.

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

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

The description clearly states a specific verb and resource: concatenating an ordered list of video and/or still-image segments from public HTTPS URLs into one continuous, fresh-encoded output. It also names the common editorial use cases (head slate, tail slate, mid-roll insert, all-video splice), which distinguishes it from simple single-file conversion 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 gives strong usage context: when to use image-first/image-last/image-middle segments, when to use all-video segments, and required constraints (at least 2 segments, max 8, at least one video, public URLs). It does not explicitly name sibling alternatives or state when NOT to use this tool versus conform_from_url or conform_splice_media, so it falls just 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?

Beyond the annotations, the description discloses that the tool produces a fresh-encoded output and runs asynchronously, requiring polling. It also explains error semantics in detail: structured errors are real Botverse errors, while bare HTTP 500s are connector/sandbox issues. This adds substantial behavioral context that 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?

The core purpose and usage are front-loaded in the first two sentences, and the workflow is stated compactly. The reliability/fallback paragraph is lengthy and includes a CLI example that is only loosely related to this specific tool, but it is organized under a clear heading and provides valuable operational guidance. Overall it is appropriately sized with minor 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 selection criteria, invocation workflow, error handling, and fallback behavior, while the input schema and output schema handle parameter and return-value documentation. For a tool with nested parameters and asynchronous output, the description is sufficiently 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 100%, so the baseline is 3. The description reinforces that segments come from get_upload_url and that options are the same as conform_splice_from_url, but these details are already present in the schema. It does not add new parameter-level meaning beyond what the schema already documents.

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: 'Concatenate an ordered list of already-uploaded video and/or still-image segments ... into one continuous, fresh-encoded output.' It also explicitly distinguishes this tool from conform_splice_from_url by noting it is for local files or files too large to fetch by URL. This clearly differentiates it from its main 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 explicitly states when to use this tool versus conform_splice_from_url: 'use this for local files or files too large to fetch by URL.' It also gives the follow-up workflow of polling get_job_status and then get_download_url. The reliability/fallback section further guides agent behavior in error cases.

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, it discloses that execution is server-side and sandbox-safe, has a 4 MB content limit, incurs a flat $0.05 per-file fee, returns a job_id requiring polling, and offers inline or download retrieval. No contradictions with readOnlyHint=false or other 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?

It is front-loaded with purpose and routing, and most sentences carry useful operational detail. It loses a point for restating the supported input/output format enums that the schema already lists, making it longer than strictly necessary.

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 paid asynchronous converter with sandbox restrictions, it covers the full call workflow: input limits, alternative tools, job_id polling, output retrieval methods, and cost. With the output schema also present, nothing needed 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 coverage is 100%, so the schema already defines content, encoding, and format parameters. The description adds a meaningful invocation constraint not in the schema: up to 4 MB for the content parameter, and confirms base64 for binary inputs like .docx.

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 and resource ('Convert a document inline') and distinguishes this route from siblings such as convert_from_url, convert_file, and the CLI, so an agent can select it without opening other schemas.

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

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

It gives explicit when-to-use guidance: preferred for documents and sandboxed agent environments, with a 4 MB limit, and names convert_from_url for larger inputs plus the botverse CLI for non-sandboxed local files. This covers when and when-not to invoke it.

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

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

The description discloses critical behavioral traits beyond the annotations: it returns a job_id immediately (async behavior), has a flat fee of $0.05 per file, supports specific input/output formats, and requires a multi-step upload workflow. Annotations only indicate non-read-only and non-destructive; description adds substantial context and does not contradict 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 front-loaded with the primary purpose. While it includes a detailed workflow, every sentence carries necessary information (steps, async result, formats, cost, alternatives). It is longer than minimal but earns its length; still, it could be slightly more concise by merging some procedural 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?

For a tool requiring a multi-step upload workflow, the description is exceptionally complete: it outlines prerequisites, the exact sequence of calls, the immediate return value, supported formats, cost, and fallback alternatives. It also covers the sandbox limitation. No critical context 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 input schema already fully documents both parameters (object_key and output_format) with descriptions and an enum. The description restates the output formats and mentions that object_key comes from get_upload_url, but does not add new semantic meaning beyond the schema. With 100% schema coverage, baseline of 3 is appropriate.

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 the tool's purpose clearly: 'Offload a document conversion to Botverse using an already-uploaded file.' It specifies the verb (convert), the resource (an uploaded file), and the context (document conversion). It also distinguishes from siblings by explaining the upload prerequisite and mentioning alternatives (convert_content, convert_from_url) for different scenarios.

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: it spells out a three-step workflow, says to poll get_job_status and get_download_url, and explicitly warns 'If you are in a sandboxed environment where the get_upload_url PUT is blocked, do not use this tool' with named alternatives. This is exactly the kind of usage clarity expected.

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 well beyond the annotations (which only cover readOnly/openWorld/idempotent/destructive) by disclosing the async job model, that it returns a job_id immediately, the 5s polling cadence, the next tools to call, the flat $0.05 fee, and sandbox-safety in claude.ai/Desktop/Cursor. This is exactly the mutation-lifecycle context annotations cannot express.

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?

Long but front-loaded: purpose first, then routing guidance, then the async workflow and pricing. Nearly every sentence carries actionable information, though 'Runs entirely server-side' is stated twice and the density is slightly high for a two-parameter tool.

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 an output schema existing, the description supplies the missing operational context an agent needs: the async polling loop, the two terminal retrieval tools, format support, and cost. Nothing needed to invoke or follow up on this tool is absent.

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 already 100%, so baseline is 3, but the description adds real meaning: it enumerates supported input formats (md, html, rst, txt, docx) and output formats (docx, pdf, html, txt, md, rst, xlsx) and explains that share links auto-resolve to a file, which clarifies source_url semantics beyond 'Public HTTPS URL'.

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 (document conversion from a public URL) and distinguishes itself from siblings by naming convert_content and by scope of input source. An agent can tell it apart from convert_file, convert_content, and the transcode/conform/transcribe families without opening any schema.

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

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

Explicitly says when to use it (source document is at a public URL; Dropbox/Drive/OneDrive/SharePoint/Box share links auto-resolve) and when not to (if content is already a string, use convert_content; for files too large for convert_content's 4 MB inline limit). Names the alternative and the selecting condition.

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 well beyond the annotations by disclosing URL lifetime (24 hours) and a critical operational constraint the annotations cannot express: the download host is blocked in sandboxed agent environments, with the failure mode and workaround named.

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

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

Front-loads the core action, then adds the precondition, the expiry, and the sandbox warning in priority order. No filler sentences; every clause carries actionable information.

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

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

An output schema exists so return values need no explanation, and the description still covers timing, lifetime, and the environment-dependent failure path. Nothing an agent needs to call this 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 the single job_id parameter is fully documented in the schema, including its provenance. The description adds no further parameter detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a presigned HTTPS URL to download the completed output file') and implicitly distinguishes itself from get_output_content, the inline-bytes alternative named later in the text.

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 precondition ('Call after get_job_status returns complete') and an explicit when-not/alternative branch ('If you are in a sandbox, use get_output_content instead'), naming the exact environments affected.

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, openWorld, and non-destructive, but the description adds genuine operational behavior: polling cadence, expected latency, the meaning of intermediate statuses, and the indefinite-polling contract. These are traits an agent cannot infer from the annotations alone.

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 efficient, with the core instruction (poll every 5 seconds) leading. The final two sentences overlap, since 'keep polling indefinitely' and 'do not stop polling after a fixed number of attempts' express the same rule, creating mild 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 polling tool with an output schema and rich annotations, the description supplies everything the agent needs: cadence, terminal states, interim states, and duration expectations. Return-value shape is handled 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 coverage is 100% and the single job_id parameter is fully documented in the schema, including the producing tools. The description adds no syntax, format, or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('poll') and resource ('status of a transcode or convert job'), which scopes it away from unrelated siblings. It does not explicitly address the closely-named sibling get_workflow_status, so an agent must infer the job-vs-workflow boundary.

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 unusually prescriptive usage guidance: call every 5 seconds, treat queued/processing as normal, expect 5–15 minutes for large files, and continue until a terminal status. It explicitly says not to stop after a fixed number of attempts, closing the most common misuse path.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely non-obvious behavior beyond them: the payload is delivered inline as base64 over the tool channel, there is a hard 4 MB cap, and the network/egress failure mode that motivates the tool. Those are exactly the traits structured fields cannot express.

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

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

Three dense sentences, front-loaded with what the tool returns before the rationale and the fallback. No filler, no repetition of the title or of annotation content.

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-value documentation is unnecessary; the description still covers the caller-relevant behavior (inline base64, 4 MB ceiling, sandbox context, fallback path). 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 100% for the single required job_id, so the schema already documents the parameter. The description adds the meaningful constraint that the job must already be complete, but gives no further syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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 ('return the finished output of a completed job INLINE as base64') and immediately contrasts it with the sibling get_download_url, which is the file-fetching alternative. An agent can distinguish it from get_download_url and get_job_status 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?

Gives explicit when-to-use (sandboxed agent environments like claude.ai, Claude Desktop, Cursor where fetching a get_download_url link is blocked), a precondition (call after get_job_status returns 'complete'), and an explicit when-not-to-use plus alternative (>4 MB outputs should use get_download_url). This is a full routing decision in one paragraph.

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 behavioral details: 15-minute expiration, it's a presigned POST (not PUT), requires direct outbound network access, and fails in sandboxed environments. This goes well 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 lengthy but well-structured and information-dense. It front-loads the core purpose, then details the workflow, caveats, and alternatives—all necessary for this complex tool. No redundant sentences.

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 environmental constraints, the description covers all essential context: purpose, usage steps, network requirements, alternatives, and a summary of the response format. The output schema exists, so detailed return values are not necessary, but the description still mentions upload_url + upload_fields.

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 already provides full descriptions for both parameters (filename and content_type) with examples. The description adds no new parameter-specific semantics beyond the schema; it simply references the upload fields and object_key in the workflow context.

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 verb ('Get a presigned upload form') and the resource (upload form for any file type). It distinguishes from siblings by mentioning the subsequent use of object_key with transcribe_media, transcode_video, or convert_file.

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 when to use (when you have a file to upload) and when not to use (sandboxed environments with proxy allowlists), and names specific alternative tools (convert_content, transcode_content, convert_from_url, etc.).

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, so the safety profile is covered. The description adds the 'prepaid' aspect and the recommendation for batch jobs, but does not describe response format or any potential edge cases. With annotations present, this is adequate but not rich in behavioral detail.

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 sentences and every word earns its place. It front-loads the purpose in the first sentence and gives usage context in the second. 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?

Given the tool's simplicity (no params, safe read operation, output schema present), the description is complete. It clearly states what the tool does and when to use it. There is no missing critical information for an agent to select or invoke 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 tool has zero parameters, and the schema coverage is trivially 100%. The description correctly indicates that it is a simple read operation. Since there are no parameters to explain, the baseline of 4 applies, and the description adds no unnecessary param details.

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 'Check the current prepaid wallet balance for this Botverse account' with a specific verb and resource. It distinguishes itself from sibling tools (workflows, conversions, uploads) by focusing on wallet balance. The phrase 'for this Botverse account' adds specificity.

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 usage guidance: 'Use before large batch jobs to confirm sufficient funds.' This gives context on when to invoke the tool, though it does not explicitly mention alternatives or exclusions. Since the tool is simple and standalone, this is sufficient.

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 a critical side effect: 'Each call may advance the workflow by dispatching steps whose dependencies have completed.' This directly contradicts the readOnlyHint=true annotation, which claims no state changes. Thus, transparency is undermined by the annotation conflict.

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 extremely concise: two sentences that pack in purpose, behavior, and polling guidance. No filler or redundancy; every sentence earns its place.

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

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

For a one-parameter status polling tool, the description covers the key aspects: what it returns, how to poll, and terminal statuses. An output schema exists to explain return values, so missing step-level details are not critical. However, the side-effect behavior is not fully reconciled with the annotations, slightly reducing completeness.

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 already covers the only parameter (workflow_id) with a clear description ('Workflow ID returned by submit_workflow'), so the baseline is 3. The tool description adds no further parameter-level 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 clearly states 'Get the current status of a workflow and all its steps' with a specific verb and resource scope. It distinguishes itself from siblings like get_job_status by focusing on workflows, and the mention of step statuses adds specificity.

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 polling guidance ('Poll every 5–10 seconds until status is...') which tells when to call repeatedly. It doesn't explicitly mention alternatives or when not to use, but the polling context is clear and actionable.

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 mutation/idempotency, and the description adds valuable behavior beyond that: immediate workflow_id return, polling cadence, dependency execution, billing/auto-refill requirements, and strict reference template constraints. No contradiction with 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?

Long but organized into clear labeled sections (INTER-STEP REFERENCES, BILLING) with front-loaded purpose and return behavior. Every sentence carries operational information; the example earns its place by clarifying reference syntax.

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 complex workflow submission tool, the description covers execution model, reference syntax, billing constraints, and schema location. Output schema exists, so not describing every return field is acceptable; nothing essential for correct invocation 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 describes definition as BWDL with workflow_id/steps, and the description greatly expands this with step structure, depends_on semantics, inter-step reference syntax, a worked docx→pdf example, and input_format inference rules. This is far beyond the baseline for 100% 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 a specific verb-resource pair: 'Submit a multi-step workflow to the Botverse workflow engine.' It clearly differentiates from sibling tools by describing workflow-level orchestration (dependency order, parallel branches) rather than single-step conversions or status/cancel 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?

Provides concrete usage context: async polling with get_workflow_status, dependency/parallel semantics, billing prerequisites, and unsupported syntax. Does not explicitly state when to prefer single-step sibling tools over submit_workflow, but the multi-step framing implies it.

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

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

Beyond the annotations, the description discloses critical behaviors: returns job_id immediately, wallet debited on completion, size limit 2 GB, polling interval and duration, error semantics (structured errors vs bare HTTP 500), and fallback procedures. This is rich context that fully prepares the agent for real-world operation. No contradiction with 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 long but highly structured and every sentence carries operational weight. It starts with the core purpose, then flows through URL requirements, job polling, trimming, and error handling. The 'IMPORTANT' and 'RELIABILITY & FALLBACK' sections are well-separated and avoid 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's complexity (async job, polling, external service, nested options, output schema), the description covers all essential aspects: input constraints, size limit, wallet debit, polling behavior, error handling, and a fallback path. It is complete enough for an agent to use the tool independently, with the output schema covering return 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 coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for options.start_time and options.duration ('start_time='00:01:00', duration=120') and by explaining that share links auto-resolve. It also contextualizes source_url with supported URL types, which goes beyond the schema's simple 'Public HTTPS URL'.

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 'Offload a video or audio transcode to Botverse using a public URL — no upload step needed', clearly identifying the verb (transcode), resource (video/audio from a URL), and the distinguishing feature (no upload). It also differentiates from sibling tools like transcode_video by emphasizing URL-based input, and from transcription by specifying video/audio transcode.

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 clearly states when to use this tool (when you have a public URL or cloud share link) and gives operational instructions (poll get_job_status, handle failures). However, it does not explicitly contrast with transcode_video or other siblings, though the 'no upload step needed' implies a distinction. The fallback to CLI is an additional usage alternative.

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds the behavioral detail that matters: it is asynchronous, returns job_id immediately, has a hard cost event (wallet debited on completion), and hard input limits (≤10 min, ≤5 GB). The reliability/fallback section also discloses error semantics and distinguishes Botverse errors from MCP-connector failures. Not a 5 because polling cadence is asserted without noting whether job state is durable across retries.

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 correctly: purpose, async contract, limits, then workflow, then fallbacks. However the RELIABILITY & FALLBACK block is long and partially tangential to invoking this tool (messaging about connector failures, CLI workarounds, token waste), which dilutes an otherwise tight definition.

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 an output schema existing, the description still maps the full lifecycle (upload → job_id → poll → download) and covers limits, cost trigger, and blocked-environment alternatives. For a multi-step async mutation, 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 description coverage is 100% with nested options fully documented, so the schema does the heavy lifting and a baseline of 3 applies. The description adds the source-file size/duration constraints but no syntax or meaning for output_format/options beyond what the enum and property descriptions already say.

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 (offload a video transcode, encoding server-side) and immediately disambiguates from its siblings by naming transcode_from_url and transcode_content. An agent can distinguish this from the many conform_/convert_/transcribe_ tools without opening a schema.

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

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

Gives explicit prerequisites (must call get_upload_url first), the fallback path when that is blocked, and the downstream sequence (poll get_job_status every 5s until 'complete', then get_download_url). It states exactly when to pick each alternative, so 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?

The description discloses significant behavior beyond annotations: it returns a job_id immediately, reports live stages (converting audio → transcribing → AI augmenting → rendering), costs ~$3 per hour, requires consent, and explains error semantics including the MCP connector failure distinction. This is exemplary transparency despite minimal annotation 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 front-loaded with a clear purpose, then structured into usage, cost, consent, and reliability sections. It is lengthy but each section serves an actionable purpose; some redundancy exists (e.g., 'ONE call does everything' vs internal steps), but it remains scannable and not bloated.

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 async nature, the description covers the complete lifecycle (job submission, status polling, content retrieval), error handling, cost, consent, and fallback strategy. With an output schema present, it doesn't need to detail return values. No meaningful gaps remain.

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 schema coverage is 100%, the description adds crucial semantics: source_url can be direct or share links (Dropbox, Drive, OneDrive, SharePoint, Box) that auto-resolve; options.attendees names speakers; diarization is default true; output formats are enumerated and tied to the deliverable. This enriches the bare schema parameters.

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: 'Transcribe a video or audio file from a public HTTPS URL into a speaker-labelled transcript — ONE call does everything.' It clearly distinguishes itself from sibling conversion/transcoding tools by emphasizing speaker diarization, attendee labeling, and the broad range of output formats.

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

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

It provides an explicit usage flow: pass source_url and output_format, receive a job_id, poll get_job_status, then get_download_url/get_output_content. It also gives fallback guidance and explicitly warns against writing custom ffmpeg/transcription code. However, it does not directly compare with transcribe_media or convert_from_url, leaving some ambiguity about when to prefer this 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?

Despite annotations lacking depth, the description discloses critical behavioral traits: async job lifecycle with polling, cost per hour of audio, consent requirements, and a detailed reliability section explaining that bare HTTP 500s may come from the MCP connector layer, not Botverse. It even warns against writing custom workaround code. This goes far beyond annotation 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 long but well-structured with clear section labels (CONSENT, RELIABILITY & FALLBACK). Every sentence carries operational value, and purpose is front-loaded. However, the reliability/fallback content is quite dense and could be seen as slightly over-explained for a tool definition, keeping it at 4 rather than 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 complex async tool, the description is remarkably complete: it covers prerequisites (upload via get_upload_url), usage boundaries, consent, follow-up workflows (poll status, download), cost, error interpretation, and fallback CLI instructions. Combined with an output schema, the agent has all context needed 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 coverage is 100% with meaningful descriptions for all three parameters (object_key, output_format, options). The schema already mentions 'Same options object as transcribe_from_url' and 'The object_key returned by get_upload_url', so the description adds no new parameter-level meaning. Baseline 3 applies.

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

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

Purpose is explicit and specific: transcribe an already-uploaded video/audio file (from get_upload_url) into a speaker-labelled transcript. It clearly distinguishes from sibling `transcribe_from_url` by focusing on uploaded objects and larger files, and even names the source workflow.

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 states when to use this tool (local files or files > URL fetch limit, up to 2 GB) and references the sibling `transcribe_from_url` for URL-based cases. It also gives a full workflow (poll `get_job_status`, then retrieve) plus fallback guidance and cost/consent notes, leaving no ambiguity about usage.

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