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 significant behavioral details beyond the annotations: it runs server-side (avoiding S3 uploads), has a 4MB limit, returns a job_id requiring polling, and charges a $0.05 fee. These are crucial operational traits that annotations do not convey, enriching the agent's understanding of side effects and cost.

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, dense paragraph but is logically structured: core action, preference, limits, formats, return flow, cost, and tip. While slightly lengthy, every sentence carries essential information for this complex tool, and it is front-loaded with the primary purpose.

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 (4 params, job polling, sandbox implications, cost), the description is remarkably thorough. It covers input methods, size limits, alternatives, output formats, the polling workflow, pricing, and environment-specific recommendations. The output schema presumably handles return details, so the description is complete.

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

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

Although the schema already has 100% coverage, the description adds valuable semantic context: the 4MB limit for content and the explicit requirement to use base64 for docx. It reinforces the encoding parameter's purpose and gives a practical constraint not present in the schema.

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

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

The description clearly states the tool's function: 'Convert a document inline — pass the content directly as a string'. It distinguishes itself from the sibling convert_from_url by explicitly naming it as the alternative for larger content, making it unmistakable which tool to use for inline content.

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

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

The description gives explicit usage context: 'PREFERRED route for documents... use in sandboxed agent environments' and 'For anything larger, use convert_from_url with a public URL.' It also provides a CLI alternative for local, non-sandboxed environments, covering both when-to-use and when-not-to-use.

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?

Annotations provide only basic safety hints. The description adds critical behavioral context: asynchronous processing (returns job_id), polling workflow, server-side execution, auto-resolution of share links, and a flat fee. 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?

Though lengthy, every sentence provides distinct value: purpose, usage, alternatives, formats, workflow, cost. Structured logically and front-loaded with the core action.

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?

Complex asynchronous tool with cost and sandbox constraints. Description covers return value, next steps, polling, retrieval methods, and limitations (4 MB inline limit for alternative). Output schema exists and is not redundant with description.

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 already has 100% coverage with descriptions for both parameters. The description adds value by explaining auto-resolution of share links for source_url and the xlsx output meaning (tables extracted), which goes beyond the schema.

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

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

The description clearly states what the tool does with a specific verb ('offload a document conversion') and resource (document from a URL). It distinguishes from siblings by explicitly directing string content to convert_content and mentioning supported 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?

Explicit when-to-use guidance: 'Use this when the source document is at a public URL.' It also mentions alternatives (convert_content) and context (sandboxed environments, large files). No exclusions left ambiguous.

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?

Discloses URL expiration (24 hours) and the direct S3 download limitation in sandboxed agent environments, which is beyond the readOnlyHint and idempotentHint annotations. 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?

Three sentences, front-loaded with the primary action, followed by timing and a critical caveat. No filler or 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?

The tool's simplicity (single parameter) and rich annotations make the description sufficient. It covers the usage sequence, expiry, and sandbox workaround, which are the key contextual pieces.

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 documents job_id with complete provenance from transcode_video, transcode_from_url, or any convert tool. The description adds no further parameter-level detail, so baseline 3 for full 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?

The description clearly states the tool's function: getting a presigned HTTPS URL to download the completed output file. It distinguishes itself from siblings like get_output_content by specifying the URL-based download mechanism.

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 instructs when to call (after get_job_status returns 'complete') and provides a clear alternative for sandboxed environments (get_output_content). This directly addresses when to use vs alternatives.

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 traits: intermediate statuses like 'queued' or 'processing' are normal, large files take 5–15 minutes, and polling must continue indefinitely without a fixed attempt limit. This adds significant value beyond the readOnlyHint and idempotentHint annotations, which only indicate safety. It also warns against stopping early, preventing agent misuse.

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 purpose and then provides actionable polling rules. Every sentence serves a distinct purpose: status scope, polling interval, expected durations, and a caution against premature stopping. No redundant filler exists.

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

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

The tool is simple with one parameter and a full output schema. The description covers all necessary operational context: how often to poll, what statuses to expect, and how long to continue. Combined with annotations, there is no missing information for an agent to correctly invoke the 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?

The input schema already fully documents job_id with descriptions listing the exact source tools. The description does not add additional parameter semantics, so it relies on the schema's comprehensive coverage. This meets the baseline for 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?

The description states 'Poll the status of a transcode or convert job,' clearly identifying the action and resource. It distinguishes from sibling tools like get_workflow_status by specifying the job type, and also provides explicit polling behavior. This is a specific, non-tautological statement.

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 polling instructions: 'Call every 5 seconds until status is complete or failed' and 'Keep polling indefinitely until a terminal status is reached.' It defines the scope as transcode/convert jobs, but does not explicitly contrast with alternative tools like get_workflow_status. Therefore, it provides clear context and usage guidance, but misses explicit alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds genuinely useful behavioral context: outputs are base64-encoded, delivered inline over a channel that 'always works', capped at 4 MB, and only available for completed jobs. This exceeds what annotations alone convey.

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 with the core purpose front-loaded, followed by use context, then size limit and alternative. Every sentence adds distinct value, with no redundant wording or unnecessary elaboration.

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

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

For a single-parameter tool with rich annotations and an output schema, the description covers purpose, timing, environment restrictions, size cap, and fallback tool. Nothing essential is missing for an agent to select and 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 only parameter, job_id, has full schema description coverage ('Job ID from any convert or transcode job'). The description does not add extra parameter-specific details, but given the schema already documents the parameter well, the baseline score 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?

The description opens with a specific verb and resource: 'Return the finished output of a completed job INLINE as base64 — no S3 download.' It clearly distinguishes this tool from get_download_url by highlighting the inline base64 delivery mechanism and the completed-job precondition.

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

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

It explicitly states when to use this tool (sandboxed agent environments where get_download_url is blocked), when to call it (after get_job_status returns 'complete'), and provides a concrete alternative for larger outputs (get_download_url). This gives the agent unambiguous selection criteria.

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?

The description discloses immediate return with workflow_id, polling interval, billing demands, and unsupported template syntax. This goes beyond annotations, which only provide readOnly/idempotent hints, and no contradictions exist.

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

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

The description is dense but every sentence adds critical information: execution model, references, billing, and schema link. It is front-loaded with the primary action and remains structured with clear sections (e.g., INTER-STEP REFERENCES, BILLING).

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 semantics, reference syntax, billing rules, and links to the schema. It is sufficient for an agent to select and invoke the tool correctly.

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

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

Although the schema covers the definition object's required fields, the description enriches it with dependency ordering, inter-step reference syntax ($.steps...), workflow parameter references, and an example chain. This significantly aids correct parameter construction.

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

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

The description clearly states the tool's function: submitting a multi-step workflow to the Botverse workflow engine. It distinguishes from sibling single-step conversion tools by emphasizing multi-step execution and dependency ordering.

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 explicit usage context: poll get_workflow_status after submission, dependency and parallel execution, and billing prerequisites for transcode/transcribe steps. It implies this tool is for multi-step workflows versus single-step siblings, though it doesn't explicitly name alternatives.

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?

The description discloses key behavioral traits beyond annotations: server-side encoding, immediate job_id return, source limits (≤10 min, ≤5 GB), wallet debit on completion, and error-handling semantics (structured errors vs. connector failures). 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 well-structured and front-loaded: core function first, then constraints, then workflow, then alternatives and fallback. Each section earns its place, though the reliability/fallback section is somewhat verbose and could be trimmed without losing essential guidance.

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

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

The description is complete for a complex async transcoding tool: it covers workflow, constraints, side effects, and error handling. An output schema exists, so return values need no explanation. This provides the agent with everything needed to select and 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% and parameter descriptions are thorough. The description does not add parameter-specific meaning beyond schema, but does add context about object_key originating from get_upload_url. Baseline 3 is appropriate since the schema carries the burden.

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 it offloads a video transcode to Botverse, runs server-side, and returns a job_id. It distinguishes itself from siblings by explicitly requiring get_upload_url first and naming transcode_from_url/transcode_content as alternatives for sandboxed environments.

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 workflow: requires get_upload_url, poll get_job_status every 5s, then get_download_url. Clearly states when to use alternatives (sandboxed environment where upload POST is blocked) and gives fallback instructions to use the CLI rather than reinventing functionality.

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.