tokportal_fix_bundle_video_download

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

With annotations providing only empty hints (all false), the description adds useful behavioral details like coverage prerequisites, automatic renewal, and the condition that no mutation occurs if coverage fails. However, it fails to describe the return value or what happens on success, leaving a gap in transparency for a mutation tool.

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, starting with the core purpose and then adding necessary conditional details. It is not overly verbose, though the conditional block could be slightly better structured for readability. Every sentence adds value.

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 has 4 params, nested objects, and no output schema, the description covers the core behavior and key prerequisites but omits the return value, error conditions, and the full workflow (e.g., what 'task' it triggers). This leaves the agent with incomplete understanding for a complex mutable operation.

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 each parameter already described. The description mentions 'manager-flagged broken video or carousel download URL' which indirectly explains the body parameter's purpose, but does not clarify the mutual exclusivity of video_url and carousel_images or add meaning 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 the tool fixes a broken video download by replacing a manager-flagged broken URL and clearing the issue flag. This specific verb+resource combination distinguishes it from sibling tools like tokportal_configure_bundle_video or tokportal_patch_bundle_video which handle other video modifications.

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 context about required account coverage and automatic renewal behavior, but does not explicitly state when to use this tool over alternatives or when not to use it. It implies usage for flagged broken downloads but lacks comparative guidance against tools like tokportal_reset_bundle_video.

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