tokportal_create_bundles_bulk

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

Annotations only indicate non-readOnly, non-idempotent, and non-destructive, but the description goes far beyond by detailing atomic rollback on failure, immediate credit debit (not at publication), consumption of contract_bundle_allowance slots in deterministic order, and partial price for batches crossing the final slot. It also explains the advanced warming options' behavior (later configuration, auto-cancel after 14 days). No contradiction with 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 comprehensive but moderately long. It front-loads the core purpose in the first sentence but includes dense technical details (allowance slots, contract prices, advanced warming nuances) that could be more structured. Every sentence earns its place, but the length relative to context signals (2 params, no output schema) suggests minor trimming or bullet-pointing would improve readability.

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 object, multiple warming options, rollback semantics, credit costing) and no output schema, the description covers key aspects: return values implied by external_ref and bundle IDs, credit mechanics, rollback behavior, and warming configuration paths. It's complete for a bulk creation tool, though missing explicit mention of potential error states beyond rollback.

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 detailed descriptions on parameters like external_ref, wants_deep_warming, advanced_warming_terms, and advanced_warming_terms_count. The description adds value by explaining the batch-level semantics of external_ref (not a retry mechanism) and the interplay between the two advanced warming alternatives, but the schema already covers most nuances well.

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 uses specific verbs ('Create', 'pays') and a clear resource ('bundles in bulk'), and explicitly states an atomic creation checkout with immediate credit debit. This distinguishes it from its close sibling tokportal_create_bundle (single) and other tools (e.g., tokportal_configure_bundle_warming_terms) by clarifying the batch nature and payment mechanics.

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 detailed when-to-use guidance (for bulk creation with atomic checkout), when-not-to-use (for single bundles use create_bundle, for configuration after purchase use warming-terms endpoints), and explicit alternatives (advanced_warming_terms vs advanced_warming_terms_count). It also explains gotchas like external_ref not being an idempotency key and the rollback behavior on failure.

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