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

Annotations are all false/noisy (readOnlyHint=false, destructiveHint=false, etc.), so they provide little signal; the description carries the burden and adds useful workflow context by clarifying the conceptual difference between a stay and accommodation. The only gap is not describing what happens on duplicate calls or how the stay relates to check-in/checkout dates, but since annotations don't declare idempotency or safety, there's no contradiction and the description does enough.

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, zero wasted words. The em-dash aside is genuinely useful, not decorative, and the pointer to create_accommodation serves double duty as both usage guidance and differentiation. Every phrase earns its place.

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 create tool with 9 params, no enums, no nested objects, and no output schema (so nothing to describe about return values), the description covers the essential workflow context well. It fully explains the conceptual model needed to use the tool correctly. Slightly more emphasis on preconditions (e.g., does the trip need to exist? what happens with overlapping stays?) would push it to a 5, but the current coverage is solid.

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 67% (6/9 params documented), just under the 80% threshold for a baseline-3. The description itself contributes no parameter-level semantics, and the undocumented params (journey_id, notes, checkout_flexible) are relatively self-explanatory. The description stays within its lane — neither helping nor hurting — landing at a solid 3 for acceptable-but-unremarkable parameter support.

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?

Uses a specific verb-resource pair ('Add a stay...to a trip') and immediately clarifies the domain meaning with the parenthetical 'a stop in a city'. It distinguishes itself from its closest sibling (create_accommodation) by explaining that a stay gets a destination onto the itinerary, which is exactly the kind of scoping the rubric rewards.

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?

Explicitly positions the tool within the workflow ('This is how a destination gets onto the itinerary') and names the exact alternative ('book lodging for it with create_accommodation on the same dates'). This tells the agent when to use this tool versus the confusable sibling, and even implies a temporal relationship between the two calls.

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