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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantive context: prior-time history is preserved, the old capacity is freed, and transactional notifications are sent. It also explains how to retry safely by reusing the same idempotency key, which is concrete operational guidance beyond the boolean hint.

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?

Two dense sentences with no filler; the authorization precondition is front-loaded and the side effects and retry rule follow. It is appropriately sized for a destructive mutation, though the second sentence packs several distinct effects into one long clause.

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?

An output schema exists, so return values need not be described. The description covers the authorization prerequisite, the mutations performed, and idempotent retry behavior, leaving only the peripheral source/correlation/session parameters unexplained.

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 only 20%, so the description must carry more weight. It clarifies the authorization token's origin and the idempotency key's retry semantics, but source, correlation_id, and anonymous_session_id are left entirely to the bare schema types.

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 states a specific verb+resource ('moves the existing booking to the reserved available time') and the title confirms it is a reschedule of an approved appointment. It distinguishes itself from prepare_service_booking_change by requiring the one-time approval token rather than producing a change, though it never names that sibling explicitly.

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?

'Use this only with the one-time approval issued after the user confirms the exact reschedule inside the protected management form' gives a clear and restrictive precondition for invocation. It lacks explicit routing to alternatives (e.g. prepare_service_booking_change for the pre-approval step), so it stops short of full when/when-not guidance.

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