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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description needn't restate that. It adds real behavioral context beyond the annotations: photographs and the 360° tour appear only 'when published', and child catalogues are opt-in additions to the same payload rather than a separate round trip.

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 sentences, front-loaded with what the record is, then the optional payload extension. The field enumeration is long but each item earns its place because there is no output schema to describe return contents.

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?

With no output schema, the description bears the burden of describing the return value and does so thoroughly, including the conditional inclusion of photos and tours. Minor gaps remain: no behavior for an unknown slug, and no positioning relative to resolve_resort or search_resorts for discovery workflows.

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 both `slug` and `include` are already documented in the schema. The description restates the five attachable catalogues in the same order as the enum and confirms attachment is optional, but adds no syntax, sizing, or ordering detail beyond 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 description states a single record retrieval and enumerates exactly what the record contains (location, transfers, meal plans, counts, policies, sustainability, brand, photos, 360° tour, optional child catalogues). This distinguishes it from leaf siblings like get_resort_gallery or get_vr_tour by establishing that those artifacts are included here when published. It never explicitly names a sibling to contrast with, keeping it short of a 5.

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?

'Optionally attaches the child catalogues ... in the same call' implies you should use `include` rather than calling list_villas/list_dining separately, which is useful implicit routing. However, there is no guidance on when to use this versus resolve_resort or search_resorts, and no stated prerequisites or exclusions.

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