tokportal_reset_bundle_video

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

Annotations already indicate destructiveHint=true, so the mutation is expected. The description adds useful behavioral context: the operation may not execute if coverage cannot renew, and it mentions automatic renewal behavior. However, it fails to disclose what happens on success (e.g., the new state of the slot) and what the return value is. With no output schema, the description carries a heavier burden that it only partially meets.

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: the first states the purpose, the second adds conditions. It is reasonably brief and avoids unnecessary detail, though the second sentence is dense with multiple clauses. It is front-loaded and efficient for a destructive tool with complex prerequisites.

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 having good schema coverage and some behavioral notes, the description lacks essential context. There is no explanation of what 'reset' accomplishes, no return value or confirmation behavior, no mention of ordering relative to other bundle operations (e.g., does it need to follow configure or precede publish?), and no link to related tools. For a destructive operation with no output schema, this is incomplete.

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 each parameter (id, position, idempotency_key) already has a clear definition in the schema. The tool description adds no extra meaning or usage hints beyond what is already structured. Baseline of 3 is appropriate since the schema does the heavy lifting.

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 starts with 'Reset one video slot,' which is a clear verb-resource pair, but it never defines what 'reset' actually does to the video slot. It focuses on coverage and renewal conditions rather than the core operation, leaving ambiguity about whether it removes, reinitializes, or repositions the video. Compared to siblings like configure_bundle_video or publish_bundle_video, the exact scope of 'reset' is not differentiated.

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 zero guidance on when to use this tool instead of alternatives like unschedule_bundle_video, finalize_bundle_video, or configure_bundle_video. It does not mention prerequisites beyond coverage conditions, nor does it offer when-not use cases. The agent is left to infer context from the tool name alone.

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