tokportal_create_bundle

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

The description extensively discloses behavioral traits not covered by annotations: immediate credit debit, server-side cost calculation, allowance slot consumption, auto-cancellation of unconfigured warming terms, refund policies, and the distinct roles of external_ref and idempotency_key. This goes far beyond the minimal annotation set (readOnlyHint=false, etc.) and fully informs the agent about side effects and guarantees.

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?

Despite being long, every sentence carries essential information. The description is front-loaded with the core action ('Create a bundle') and then logically flows through payment, credit costs, allowance details, warming options, and idempotency. No superfluous text; it is as concise as complexity demands.

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 (nested body, multiple conditional fields, business rules around credits and refunds) and the absence of an output schema, the description covers nearly every aspect needed for correct invocation: creation types, payment timing, cost calculation, advanced warming configuration, auto-cancellation, and duplicate detection. It is complete enough for an agent to use without guessing.

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 schema already provides 100% coverage with detailed parameter descriptions, so the baseline is 3. The tool description adds significant overarching context (credit debit timing, allowance consumption, auto-cancellation, cutoff for free trial) that enriches understanding of why parameters behave as they do, though it does not describe individual parameters in new detail. This elevates the score to 4.

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 'Create a bundle' and elaborates on three distinct bundle types (account-only, account-and-videos, videos-only), making the tool's purpose very specific. While it doesn't explicitly differentiate from sibling tools like tokportal_create_bundles_bulk, the naming convention and detailed type descriptions suffice to identify this as the tool for single-bundle creation.

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 no explicit guidance on when to use this tool versus siblings or alternatives. It does not mention when not to use it, nor does it reference other tools for different scenarios (e.g., bulk creation, publishing, updating). The internal guidance on bundle types is about configuring the request, not tool selection.

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