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

Annotations already declare readOnly/destructive/openWorld, so the description earns credit for adding substantive context beyond them: the 548-day window (created or checked out), the fact that guest email, phone and card details are withheld, and that a Cotlet API key with app access is required. These are real behavioral disclosures an agent needs before calling. Return format/pagination sizing is not covered, keeping it from a 5.

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?

Front-loaded with purpose and return fields, and every sentence is largely useful. The 548-day limit is effectively stated twice, which is minor redundancy, but the second mention adds the created-or-checked-out nuance so it is not pure repetition.

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 correctly enumerates the returned fields and covers the key gaps: date-window limit, redacted guest data, required credentials, and the pointer to get_reservation. Pagination behavior around the limit/cursor params is left to the schema, which is a small residual gap.

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% and all nine parameters carry their own descriptions and enum values, so the schema does the heavy lifting. The description adds no field-level semantics (e.g., interactions between from/to and date_type) and only mentions booking_reference, which is not even a parameter of this tool. Baseline 3 is appropriate.

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?

States a specific verb and resource (list reservations) plus the fields returned (channel, status, dates, room, total), and explicitly distinguishes itself from get_reservation by saying to pass booking_reference there for the full record. An agent can tell this apart from its sibling without opening either 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?

Gives clear context: this returns filtered summaries, and it names the alternative (get_reservation) for the full record. It also states the 548-day search window as a scope constraint. It stops short of explicit when-not guidance (e.g., when to prefer this over a status/channel-specific route), so a 4 rather than 5.

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