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

Beyond the annotations (which only declare non-read-only, idempotent, non-destructive), the description discloses the two-phase preview/commit protocol, the requirement to show changes to the user before committing, idempotencyKey reuse for retries, and the patch-like semantics that omitting a field preserves it while null clears nullable fields. These are behavioral facts the agent cannot derive from the annotation hints alone.

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 critical safety information (preview first, commit only after approval, never manufacture approval) is front-loaded, and the sentences are dense rather than padded. It runs slightly long and the closing 'if cruise tools are unavailable' sentence is a separate topic that could be tighter, but no sentence is redundant.

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?

For a nested, multi-operation mutation tool with an output schema and annotations already in place, the description covers the one thing structured fields cannot: the mandatory preview-approve-commit sequence and retry semantics. Nothing an agent needs to invoke it safely appears to be missing.

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 description explains the workflow role of expectedVersion and confirmationToken, but both are already documented in the schema at similar depth. The bulk of the parameter surface — the operations array and its per-kind fields (CreateCruise, AddDay) — is only touched obliquely through the 'never substitute a segment type' warning, leaving the actual operation vocabulary to 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 opening sentence gives a specific verb and resource ('Preview and commit cruise create operations atomically') and the later sentence scopes it to commercial cruise reservations and sea/port days via cruise_* tools. It does not explicitly name cruise_day_create or cruise_update as the non-equivalent siblings, so an agent must infer the boundary from the 'cruise_*' phrasing rather than a direct contrast.

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?

It spells out the required ordering (call cruise_get first for expectedVersion), the preview-vs-commit trigger (omit confirmationToken to preview, resend unchanged request with the token only after approval), and the exclusion rule (never substitute Activity, CruiseActivity, or another segment type for a cruise day). It also gives a fallback when the cruise tools are unavailable, which is explicit when-not guidance.

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