tokportal_reset_bundle_video

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

Annotations declare destructiveHint=true, which the description supports by explaining conditions under which 'no task or media mutation starts.' The description adds detail beyond annotations: it discloses the renewal behavior, inheritance of stored rate, and what happens if Coverage cannot renew. This provides good safety context for a mutation tool without contradicting 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 three sentences long and front-loads the primary action logically. Each sentence earns its place: first states the action, second covers prerequisites, third explains the renewal behavior and fallback. The only minor inefficiency is the specific technical phrasing ('bundle resolves to a delivered saved account') which could be condensed without loss.

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 3 parameters with full schema coverage, no output schema, and clear destructive annotations, the description is largely complete. It explains the precondition, the automatic renewal mechanism, and the fallback no-op. The only gap is the lack of clarifying what happens after a successful reset (e.g., any confirmation or next steps), but the tool's context within a bundle workflow makes this acceptable.

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% with all three parameters documented (id, position, idempotency_key). The description adds business logic around the 'position' parameter by clarifying it refers to a 'video slot,' and hints at the state machine (resolved bundle, active period). The idempotency_key parameter is mentioned in the description implicitly through the safe-retry context, adding value 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 title and description clearly state the tool resets one video slot. The description provides context about when the bundle resolves to a delivered saved account, which adds meaning. It is distinct from siblings like tokportal_configure_bundle_video or tokportal_finalize_bundle_video, though the specific effect of 'reset' versus other video operations (e.g., configure, patch, unschedule) could be sharper.

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 prerequisites (active TokPortal Coverage or permanently grandfathered) and the automatic renewal behavior. However, it does not explicitly state when to use this tool versus alternatives like tokportal_configure_bundle_video for modifying slots, or tokportal_finalize_bundle_video for completion steps. The usage context is implied but lacks direct comparisons or exclusions.

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