Botverse

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

Description goes beyond annotations by explaining that queued/dispatched steps are cancelled, completed steps are not reversed, and billing only applies to completed steps. This adds critical behavioral context not covered by 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 concise sentences, front-loaded with the primary action. Every sentence adds specific value without redundancy or 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?

Given the tool's simplicity (one parameter, output schema present), the description fully covers cancellation behavior, impact on steps, and billing. No gaps for effective use.

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?

Single parameter 'workflow_id' has 100% schema coverage with a description. The tool description adds no additional meaning beyond the schema, so baseline score 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 clearly states 'Cancel an in-progress workflow' with a specific verb and resource. It distinguishes from sibling tools like submit_workflow and get_workflow_status by focusing on cancellation.

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 use cases for cancellation and includes billing implications. While it doesn't explicitly list when not to use or alternative tools, the context is clear and sufficient for an agent.

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 basic hints (readOnlyHint=false, destructiveHint=false, etc.), but the description adds critical behavioral context: a hard 10K character limit, a flat fee of $0.05 per file, supported input and output formats, and encoding requirements. This goes well beyond what annotations convey and fully informs the agent of constraints and costs.

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 packs essential information: purpose, usage constraints, limit, alternative, formats, and cost. It is concise with no irrelevant details. Minor improvement could be structuring with bullet points or short sentences for faster scanning, but the current form is efficient.

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 parameters, 3 required, and an output schema exists), the description covers all necessary aspects: what it does, when to use, limits, formats, cost, and alternative. Since an output schema is present, the description does not need to explain return values. It is fully 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 coverage is 100% with all parameters having descriptions. The description adds value by clarifying that the content parameter accepts either plain text or base64 (for docx), and reiterates the enum values for input/output formats. It also mentions the flat fee, which is external to the schema. However, many details (like default encoding) are already in the schema, so the added value is moderate.

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

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

The description clearly states the action ('Offload an inline document conversion'), the resource ('content directly as a string'), and the method ('to Botverse'). It distinguishes from the sibling tool convert_from_url by specifying when to use this tool (self-generated content under 10K characters) and when not to, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool ('content you generated yourself, under 10,000 characters') and when not to use it ('content longer than 10,000 characters or from uploaded/external file'). It also names the alternative tool (convert_from_url) and provides clear guidance on what to tell the user in that 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?

Describes async behavior ('returns a job_id immediately'), server-side processing, and flat fee ($0.05). Annotations already declare non-destructive and non-idempotent; the description adds valuable context about cost and polling workflow beyond what annotations provide.

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

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

Single, well-structured paragraph that front-loads the purpose, lists steps, formats, and cost. Every sentence adds value, with no fluff.

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 two simple parameters, full schema descriptions, and an existing output schema (likely including job_id), the description fully covers the conversion workflow, supported formats, cost, and polling necessity. No 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?

Schema coverage is 100% and both parameters (object_key, output_format) are described with allowed values. The description adds that object_key comes from get_upload_url, but overall does not significantly enhance understanding 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?

Clearly states the tool converts an already-uploaded file via Botverse, with specific verb ('offload a document conversion') and resource ('file'). Lists supported input and output formats, distinguishing it from siblings like convert_content or convert_from_url.

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 a clear multi-step workflow (upload first, then call convert_file, poll status, download). Implicitly differentiates from alternatives by specifying the necessary preceding steps, but does not explicitly state when to avoid this tool in favor of convert_content or convert_from_url.

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 it runs server-side, returns a job_id, requires polling, and charges $0.05 per file, which adds context beyond the annotations (readOnlyHint=false, openWorldHint=true). No contradiction.

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

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

Front-loaded with main benefit. Contains four sentences, each providing distinct information. Minor redundancy in listing output formats again, but overall efficient.

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

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

Given the tool's complexity (2 params, output schema likely present), the description covers all essential aspects: purpose, input constraints, output behavior, polling process, and cost. No 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 coverage is 100% so baseline is 3. Description adds value by explaining source_url accepts share links from various services and lists supported input formats (md, html, rst, txt, docx), which are not in the schema. However, output_format enum is repeated from 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?

Clearly states the tool converts documents from a public URL, specifies the verb 'convert' and resource 'URL'. Differentiates from sibling tool convert_content which handles string 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?

Explicitly says when to use (public URL, including share links from Dropbox, etc.) and when not to (if content is already a string, use convert_content). Provides clear 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 already indicate safe, idempotent, read-only behavior. Description adds the crucial expiration detail (24 hours) and the dependency on job completion, enhancing transparency without contradiction.

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?

Two sentences, no fluff, front-loaded with the key action and resource.

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 low complexity (one required parameter, simple output schema), the description fully covers purpose, usage condition, and expiration, making it 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?

With 100% schema description coverage, the baseline is 3. The description adds value by specifying where the job_id comes from (output of specific tools), but this is already hinted 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 identifies the action (get a presigned HTTPS URL), the resource (completed output file), and distinguishes it from sibling tools by specifying the prerequisite of a completed job.

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

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

Explicitly states the condition for use ('Call after get_job_status returns complete'), implying when not to use, and provides context on URL expiration (24 hours).

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 safe, idempotent behavior. The description adds critical behavioral context: polling strategy, expected statuses, time estimates, and indefinite retry logic. This goes well beyond annotations.

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

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

The description is concise (3 sentences), front-loads the purpose, and every sentence provides essential guidance without redundancy.

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

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

Given the presence of an output schema (return values documented), the description covers all necessary aspects: polling behavior, terminal conditions, timing, and error handling instructions. It is complete for a polling 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?

Schema coverage for job_id is 100% and includes a description listing source tools. The tool description does not add further parameter meaning, so baseline score 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 clearly states the tool's purpose: polling the status of transcode or convert jobs. It uses specific verbs and resources, and the context distinguishes it from sibling tools like get_workflow_status by specifying the job type.

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 usage guidance: polling every 5 seconds until terminal status, handling normal statuses, and warning against fixed attempt limits. It does not explicitly mention alternatives or when not to use, but the guidance 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 are partially informative (readOnlyHint=false, etc.), but the description adds critical behavioral details: URL expires in 15 minutes, use PUT with raw bytes, and post-upload processing. 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 concise (three sentences), front-loaded with the primary action, and each sentence adds value without redundancy.

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

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

Given the presence of an output schema and clear instructions, the description covers the full workflow: get URL, upload, then use other tools. It is complete for the tool's complexity.

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 good parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline score 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 clearly states the tool gets a presigned PUT URL for uploading any file. It specifies file types (video, audio, document) and distinguishes from siblings by noting post-upload actions (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?

The description explains when to use the tool (to get an upload URL) and gives context about expiration and subsequent steps. However, it does not explicitly exclude cases like needing a download URL, though sibling tools imply 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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds limited behavioral context. It mentions the check operation and prepaid nature, which is consistent but not adding critical new info.

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?

Two concise sentences, the first stating purpose and the second providing usage guidance. No wasted words.

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 parameters, no required inputs, and an output schema exists), the description is complete and provides sufficient context for an agent.

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

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

The input schema has zero parameters and schema description coverage is 100%. With no parameters, the baseline is 4; the description adds no parameter details, but none are needed.

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

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

The description uses a specific verb 'Check' and identifies the resource 'prepaid wallet balance for this Botverse account.' It clearly distinguishes from sibling tools which deal with conversions, uploads, and transcoding.

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: 'Use before large batch jobs to confirm sufficient funds.' It provides clear context but does not mention alternatives or 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 states 'Each call may advance the workflow,' implying side effects, but annotations set readOnlyHint=true. This is a direct contradiction per instructions, warranting a score of 1.

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

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

Three sentences that get straight to the point: purpose, behavior, then polling advice. No extraneous words, well-structured.

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 output schema exists and annotations provide safety info, the description fully covers purpose, behavioral nuance (state advancement), and usage pattern. Nothing missing for a status-checking 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?

Schema covers the single parameter with a clear description. The tool description adds no additional parameter info beyond what schema provides, so 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?

The description clearly states the tool gets workflow status and all steps, with specific verbs and resource. It distinguishes from sibling tools like submit_workflow and cancel_workflow by noting the polling behavior and state advancement.

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 usage instructions: poll every 5-10 seconds until terminal status. However, it does not mention when to avoid using this tool or contrast with alternatives like get_job_status.

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?

Adds significant context beyond annotations: describes execution order, parallel branches, immediate return of workflow_id, polling interval, and prerequisite (auto-refill). Annotations are already present but description enriches understanding.

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

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

Three efficient sentences: first states purpose, second explains execution and polling, third warns about prerequisite. No wasted words, well-structured.

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?

Covers all necessary aspects: what it does, how to use it, how to monitor completion, and a critical prerequisite. With annotations and schema, the description is fully complete for an agent to use the tool correctly.

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

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

Schema covers definition structure; description adds BWDL language reference and schema URL, providing extra value beyond the parameter description.

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 submits a multi-step workflow to the Botverse engine, specifies execution order and parallel branches, and distinguishes itself from sibling tools like cancel_workflow and get_workflow_status.

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 instructions to poll get_workflow_status every 5–10 seconds and warns about auto-refill requirement. Lacks explicit when-not-to-use, but context makes usage clear.

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

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

The description discloses key behaviors beyond annotations: returns job_id immediately, wallet debited on completion, polling required, time estimates (5-15 min for large files), and no upload step. No contradiction with annotations (readOnlyHint false, openWorldHint true).

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 efficient, covering all important aspects in one paragraph. It uses emphasis ('IMPORTANT:') to highlight critical steps. Could be slightly more structured with bullet points, but it is clear and not verbose.

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, trimming, wallet debit), the description covers input format, size limit, trimming parameters, polling behavior, and failure handling. The output schema exists (job_id), but description already mentions return. Complete for an async transcoding 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to use start_time and duration (e.g., 'start_time=\'00:01:00\', duration=120') and clarifying output_format enum values with codec info. This goes beyond schema.

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

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

The description clearly states the tool's purpose: 'Offload a video or audio transcode to Botverse using a public URL — no upload step needed.' It specifies the action (transcode), resource (video/audio from URL), and distinguishes from siblings like convert_from_url by emphasizing no upload and share link support.

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 usage guidance: accept share links as-is, size limit 2GB, and instructions for trimming. It also gives operational advice (tell user job_id, poll every 5 seconds, never give up early). It does not explicitly contrast with siblings but implies unique behavior.

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 indicate readOnlyHint=false (write operation), openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds behavior beyond annotations: runs server-side, returns job_id immediately, wallet debited on completion. This is good transparency.

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

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

Description is two sentences, front-loaded with the main purpose and key workflow. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (3 params, 100% schema coverage, output schema exists, annotations present), the description covers the workflow: transcode, poll, get download. It lacks explicit error handling instructions but is quite complete for an async job 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?

Schema coverage is 100%, so baseline is 3. The description adds context about source constraints (≤10 min, ≤5 GB) but these are not parameters. Description does not add meaning beyond what the schema provides for the three parameters, so score 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 clearly states it offloads a video transcode, runs server-side, returns a job_id immediately, and specifies constraints (≤10 min, ≤5 GB). It distinguishes from sibling tools like transcode_from_url (which likely uses a URL) and convert_file (which may be synchronous).

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 tells when to use: for offloading transcoding with specified constraints. It also provides the workflow: poll get_job_status every 5 seconds, then get_download_url. Although it doesn't explicitly state when not to use or name alternatives, the context from siblings and the constraints give sufficient guidance.

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