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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so safety and idempotency are covered. The description adds important runtime context not in annotations: that nights are validated as a whole and cannot be edited in isolation, and that window_start/window_end must be sent together or they are merged with stored values. This is valuable, but it doesn't discuss reversibility or failure modes beyond the merge behavior.

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 front-loaded with the purpose, then the key constraint (nights), then the recommended action (window edit). It's three paragraphs and mostly earns its place, though the 'say that is what you did' instruction could be seen as slightly procedural. Still efficient for the amount of useful guidance conveyed.

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 an 8-parameter mutation tool with full schema coverage, an output schema, and rich annotations, the description covers the critical behavioral nuances (night immutability, window merge behavior) without needing to explain the return shape. The only gap is that it doesn't mention the destructiveHint implications or any permission requirements for notify channels beyond what the schema says, but those are largely covered in the schema descriptions.

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%, so the baseline is 3. The description adds meaning beyond the schema by explaining the interaction between window_start and window_end (must be sent together, one alone is merged and may leave the window too short) and by characterizing widening the window as the most useful edit. That's real semantic guidance not captured in schema descriptions.

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 opens with a specific verb and resource ('Change a route's window, party size, tent pads or notification channels') and distinguishes the tool from the sibling update_alert. It also explicitly names what it cannot edit (nights), which sharpens the boundary against related tools.

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 gives explicit when-to-use and when-not-to-use guidance: nights cannot be edited and the user should delete and recreate instead. It also recommends a workflow ('say that is what you did') and highlights the highest-value edit (widening the window), which is actionable guidance an agent can follow.

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