Hotel deals

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the description correctly spends its words elsewhere: it defines what a 'discount' means (the site's own percent off list price) and states the bookable-only filter, both non-obvious behavioral facts. It does not mention result ordering explicitly or what happens when no deal meets the threshold.

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?

Three tight sentences, front-loaded with the core behavior, then the example, then the definition and follow-up. No filler; the only marginal sentence is the eg_rooms pointer, which still earns its place as routing guidance.

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 7 parameters, 57% schema coverage and no output schema, the description should say what a deal record contains and what the 'stay' kind changes. It conveys the ranking concept but leaves the return shape and one enum ambiguous, so it is adequate rather than complete.

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 57%, and the description adds meaning mainly for the discount concept, which underpins min_discount. The 'kind' enum (hotel vs stay) is left completely unexplained in both schema and description, and limit/min_stars/nights get no elaboration, so the description does not compensate for the coverage gap.

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 plus three scoping constraints: 'List the hotels of a city', 'with the biggest discounts for the given dates', 'bookable ones only'. That is enough to tell it apart from the generic eg_search/eg_hotel siblings without opening any schema.

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 supplies a concrete trigger phrase ('any good offers in Esfahan this weekend') and an explicit follow-up path to eg_rooms for room-level detail. It stops short of naming when NOT to use it — e.g. versus eg_search or eg_specials — so an agent must still infer the boundary.

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