Yasha Hotel — Direct Booking

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

With no annotations, the description carries the full burden and does well: it discloses the returned fields (available, nights, total_cents, avg_night_cents, per-night breakdown), clarifies that the total excludes extras/breakfast/promo, and lists hard constraints (max 30 nights, no past dates). It does not state read-only status explicitly, error behavior, or whether taxes are included, so it stops short of 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, then outputs, then constraints — dense and mostly waste-free. The Booking.com/Expedia price comparison is somewhat promotional, but it is actionable context an agent could relay, so it does not badly hurt the score.

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?

This is a date-ranged read tool with no output schema, so the description must explain returns — and it does, including field names, units (euro cents) and exclusions. Gaps remain: how unavailable rooms are represented, timezone for 'past dates', and whether the total includes local taxes.

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 100%, so the baseline is 3, but the description adds genuinely new constraints not present in the schema: checkin < checkout, no past dates, and a 30-night maximum, plus the YYYY-MM-DD format reminder.

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+resource ('Check real-time room availability and exact total price') plus the enumerated return fields, which makes it clearly distinct from get_price_calendar or list_rooms in substance. It never names a sibling tool, so it gets a 4 rather than 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?

Usage is implied by the scope ('for a stay' with checkin/checkout) and the note about direct rates being cheaper gives a reason to prefer it, but there is no explicit when-to-use guidance or statement of when another tool (e.g., get_price_calendar for flexible browsing) should be used instead.

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

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

With no annotations, the description carries the full behavioral burden and does so: the booking is not confirmed until Stripe payment, unpaid bookings expire automatically, the returned payload contains booking_id, amount_cents in EUR cents and a Stripe client_secret, and the tool fails with 409 if the room became unavailable. This discloses side effects, lifecycle, payment path, and failure mode that the schema cannot express.

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?

Purpose is front-loaded and the workflow is numbered, so structure is strong. The payment paragraph is slightly verbose and repeats the schema's field list (phone, special requests, promo code) without adding much, which keeps it short of a 5.

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 11-parameter mutation with no annotations and no output schema, everything an agent needs is present: prerequisites, required traveler data, optional field guidance, the payment-confirmation requirement, the error condition, and the shape of the return value. No meaningful gap remains.

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, but the description adds real meaning: guests is capped at room capacity, breakfast applies to all guests and all nights, and extras come from list_extras. These constraints are not fully stated in the schema, though most remaining fields are simply restated.

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 ("Create a real booking at Yasha Hotel") and immediately marks the distinction from the read-only sibling by making check_availability step 1 of the workflow. An agent can tell this apart from check_availability, get_booking_status, or get_price_calendar 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?

Provides an explicit numbered workflow: confirm availability first, collect name/email, call this tool, then relay payment instructions. It also routes the agent to sibling tools for dependent data (list_extras for extra ids, validate_promo_code mentioned in the schema for promo codes) and names the condition that confirms the booking.

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

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

With no annotations, the description carries the behavioral burden and does disclose that this is an asynchronous confirmation check driven by an external payment step, plus the expected status vocabulary (pending_payment, confirmed, payment_failed). It stops short of stating polling cadence, terminal states, or whether it is read-only.

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, zero filler, with the core action first and the timing trigger second. Every clause adds information an agent needs.

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 one-parameter read tool with no output schema, the description covers what the tool is for, when to invoke it, and sample return values. A brief note on polling behavior or terminal statuses would make it fully self-sufficient.

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 100% and the single booking_id parameter is fully described by the schema as the reference returned by create_booking; the description echoes that origin but adds no format or validation detail beyond it. 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 (get booking status) and explicitly ties it to create_booking, distinguishing it from browsing siblings like check_availability or hotel_info. The parenthetical status examples make the returned domain concrete.

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 a clear usage condition: poll after the human completes the Stripe card payment to confirm the reservation. It names the sequencing relative to create_booking, though it does not state when not to call it or how often to poll.

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

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

With no annotations, the description carries the full disclosure burden, and it does add useful return semantics: prices are in euro cents and reported day-by-day, plus availability per day. However, it says nothing about permission/auth requirements, rate limits, or whether the call is purely read-only, leaving behavioral gaps for a zero-annotation tool.

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, no filler. The statement of what is returned comes first and the suggested use case follows, so the description is correctly front-loaded and every clause 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?

There is no output schema, so the description must sketch the return shape, and it does: day-by-day nightly price in euro cents plus availability. Combined with a fully described two-parameter schema, an agent has enough to call it correctly; only the absence of any mutation/safety or error-behavior note keeps it from being fully 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 description coverage is 100%, so both the month format (YYYY-MM) and the room_id default are already documented in the schema. The description reinforces the scope ('one room', 'a given month') but adds no format or constraint detail beyond what the schema already supplies, matching the baseline of 3.

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 ('Get day-by-day nightly price ... and availability for one room ... over a given month') with precise granularity (per-day, per-month, single room). It is clearly distinct from a point-in-time availability check, but it never names or contrasts with sibling tools such as check_availability, so the differentiation is inferred rather than stated.

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 a concrete usage scenario: 'Use it to suggest cheaper alternative dates when the requested dates are unavailable or expensive.' That establishes clear context for when to reach for this tool. It stops short of naming the alternative tool to use for booking or for exact-date availability, so no explicit when-not or alternative routing is provided.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does useful work: it establishes this is a static read of authoritative 'canonical facts' and explicitly states the unit convention ('Prices are in euro cents'), which prevents a costly interpretation error. It stops short of stating that the data is cached/static or noting any rate or freshness characteristics.

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 the verb and resource, then a dense field enumeration, then usage and unit notes. The field list is long but justified because the input schema is empty, so the payload has to be described somewhere; the final unit sentence is short and high-value.

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 and an empty input schema, the description must define both the call semantics (zero-arg fetch) and the return content, and it does both exhaustively, including field-by-field contents and currency units. Nothing an agent needs in order to call this tool or interpret its result is missing.

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?

The tool takes zero parameters, so per the rubric this is a baseline 4. The description correctly adds no parameter claims and instead spends its space on the payload, which is the right allocation.

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 ('Get') plus the exact resource ('canonical facts about Yasha Hotel') and enumerates the returned fields: name, rating, address, phone, email, amenities, discount, breakfast price. It is easily distinguished from data-returning siblings like list_rooms or check_availability, which cover rooms or availability rather than the property record.

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?

'Use this to answer any traveler question about the property' gives a use context but is over-broad and does not carve out boundaries against siblings such as list_rooms or list_extras, which also serve property-related questions. Usage is implied rather than routed.

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

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

With no annotations, the description carries the full burden and does disclose the return shape: prices are in euro cents and each extra carries a billing unit (per_stay, per_night, per_person_night). It does not mention any auth/permission needs, but for a zero-parameter read-only listing tool those gaps are minor.

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, both front-loaded: scope and examples first, the breakfast carve-out second. Every clause (examples, price unit, billing units, sibling pointer) adds actionable information with no filler.

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?

No output schema exists, so the description must explain what comes back, and it does (extras, euro-cent prices, billing units). Combined with the routing note to hotel_info, an agent has everything needed to call this tool correctly with zero parameters.

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?

The tool takes no parameters, so the baseline is 4. The description compensates by enumerating the billing-unit values returned, which is the closest thing to input semantics here.

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 (List) plus resource (paid extras bookable at Yasha Hotel) and grounds it with concrete examples (late check-out, parking, baby bed). It also explicitly distinguishes the breakfast option as belonging elsewhere, so an agent can tell list_extras apart from hotel_info without reading the 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?

Names the condition that selects a sibling: buffet breakfast is a separate per-guest-per-night option available via hotel_info. That is clear routing for one case, but there is no general statement of when to call list_extras versus get_price_calendar or list_rooms.

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

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

No annotations are supplied, so the description carries the burden, and it does disclose the operation is a read-only enumeration and lists the exact fields returned. It does not mention pagination, list size, or whether results are static, which are minor gaps for a zero-parameter read.

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 tight sentences: the first front-loads the operation and result shape, the second carries the only actionable downstream guidance. Nothing is wasted.

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 usefully enumerates the return payload, and with no params or annotations there is little else an agent needs. Only the absence of any note on result size/ordering keeps it from being fully 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?

The tool takes no parameters, so there is nothing to disambiguate; baseline 4 applies. The description's field enumeration describes output semantics rather than input, and no param guidance is needed.

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 ('List') and resource ('bookable room type at Yasha Hotel') and enumerates the returned fields, so an agent knows exactly what it gets. It also implicitly differentiates from siblings by positioning itself as the source of room ids consumed by check_availability and create_booking.

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?

Provides forward guidance that the returned room ids feed check_availability and create_booking, which tells the agent when this tool belongs in a workflow. It lacks an explicit 'call this first / do not use for pricing' exclusion, but the dependency chain is clear.

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

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

With no annotations, the description carries the full burden. It does disclose a valuable behavioral trait: the discount applies to room price only, excluding extras and breakfast. However, it says nothing about case sensitivity, whether validation holds or consumes the code, or how an invalid code is signalled.

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 tight sentences with the core action first and the return semantics second. Zero filler, nothing repeated from the schema.

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 usefully covers return values (valid flag and discount percentage) and scopes the discount correctly. It stops short of describing invalid-code behavior or error surfaces, which is a minor gap for a single-parameter read tool.

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% for the single 'code' parameter, so the schema already documents it. The description adds no format, casing, or length constraints beyond what the schema provides, so baseline 3 applies.

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 ('Validate') and resource ('Yasha Hotel promo code'), and goes further by describing the return semantics (validity plus percentage discount). No sibling tool overlaps with code validation, so differentiation is inherent, though no sibling is named explicitly.

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?

There is no explicit when-to-use guidance and no reference to alternatives such as create_booking or get_price_calendar. Usage is only implied by the tool name and the discount description, leaving the agent to infer the calling context.

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