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.