Bookd

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

Annotations already cover readOnly, idempotent and non-destructive semantics, so the bar is lower; the description nonetheless adds real value by enumerating the returnable statuses (including the non-obvious 'accepted = confirmed, including instant bookings') and by disclosing that no guest personal data is returned. It stops short of noting anything about lookup failure behavior for unknown IDs.

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 short sentences plus a lead-in, front-loaded with the read-only nature and the key noun, then the status enumeration. Every clause carries information; nothing is padded.

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 correctly carries the return-value burden by listing statuses and the fields returned (dates, room, price) plus a privacy caveat. For a single-parameter read tool this is complete enough to call correctly.

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?

With one parameter and 0% schema description coverage, the description compensates by naming the parameter's purpose ('by its booking_id') and supplying a concrete format example (BKD-AB12CD3), which the schema's maxLength alone does not convey. It does not state whether the ID is case-sensitive or how to obtain it.

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 (read, retrieve status) and resource (Bookd booking) with an ID format example, and enumerates the exact status values returned. It is clearly distinguishable from siblings like cancel_booking or request_booking, which mutate state.

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?

The 'Read-only' opener and the status lookup framing imply the use case (checking an existing booking's state), but the description never states when to prefer this over siblings or what preconditions apply (e.g. that the booking must already exist). Adequate but with an explicit-guidance gap.

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?

Annotations already flag destructive=true and idempotent=true, but the description adds substantial detail beyond them: confirm=false is a pure preview that changes nothing, confirm=true is irreversible, releases card holds/refunds via the property's own Stripe account, frees the dates, cancels in the connected booking system, and notifies property and guest. This is exactly the extra behavioral context the annotations cannot convey.

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 action and the safe-call protocol, and every clause adds operational meaning (refund preview, irreversibility, side effects). The final sentence is long and packs many effects together, but no sentence 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 and only 3 params, the description covers the call protocol, prerequisites, and all side effects of the destructive path, which is everything an agent needs to invoke it safely.

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 0%, so the description must carry the load, and it does: confirm is explained as preview-vs-commit, and both required parameters are named ('Needs the booking_id and the email used to book'), with the email disambiguated as the one used at booking time. It does not give formats or edge cases (e.g., email mismatch handling), keeping it below a 5.

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 ('Cancel a Bookd booking') with scope ('for the guest'), and no sibling tool offers cancellation, so it is unambiguous against booking_status/request_booking/search_stays.

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 an explicit two-step protocol: call with confirm=false first to see the refund under the property's policy, then only confirm=true after the guest explicitly agrees. This is a clear when-to-use and when-not-to-use instruction with a named prerequisite (guest consent).

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?

Annotations already declare readOnly/idempotent/non-destructive, so the opening "Read-only" is largely redundant. What earns credit is behavior annotations do not cover: it re-reads the owner's calendars on each call and holds nothing, and it discloses the response contents (room/unit prices, totals with cleaning fee and taxes, cancellation policy, deposit due).

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?

One front-loaded sentence that leads with the safety profile and then the payload; every clause carries information. It is a dense run-on list of return fields, but nothing is padding.

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 compensates by enumerating what comes back, and the calendar re-read clarifies freshness. The main gap is the undocumented guests parameter and the absence of any hint about failure modes (unavailable dates, unknown slug).

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 75%, with slug, check_in and check_out each already described (including formats) in the schema. The description only restates "one property and dates" and says nothing about the guests parameter or its bounds, so it adds little beyond structured fields.

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: live availability for one property across a date range, with the return contents enumerated (prices, totals, fees, cancellation policy, deposit). The clause "nothing is booked or held" implicitly separates it from request_booking, but no sibling is named outright, so an agent still has to infer the boundary.

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 rather than stated: read-only plus "nothing is booked or held" signals this is the pre-booking quote step before request_booking, but the description never says when to prefer it over search_stays or get_property, nor that a slug must first be discovered elsewhere. Adequate but leaves routing to inference.

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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so 'Read-only' is mildly redundant, but the description adds genuinely useful behavioral detail: deposits are 'held by the property' and taxes and cancellation policy are part of the payload. No permission or failure-mode context is given, which keeps it below 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-loads the mode and the one-line purpose before the field inventory. The enumeration is long but earns its place because there is no output schema to describe the response, and there is 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?

With no output schema, the description compensates by listing the returned fields (type, photos, amenities, house rules, rooms/units, fees, taxes, cancellation, deposit), and it covers the single input's source. Missing only minor operational detail such as error behavior for an unknown slug.

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% (pattern plus example), so the baseline is 3, but the description adds origin semantics for the slug value — it comes from search_stays or a Bookd link — which the schema does not convey.

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) and a precisely scoped resource (one Bookd property, by slug), then enumerates the payload contents. It is clearly distinguishable from sibling search_stays, whose results feed the slug input.

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 tells the agent where the slug originates ('from search_stays or a Bookd link'), which establishes the natural call sequence. It does not state when not to use it or name alternatives for other lookups, but the entry condition is unambiguous.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces this with 'Not idempotent: each call creates a new request.' Beyond that it discloses substantial behavior the annotations cannot: the payment_url/deposit flow, instant_booking live-check semantics, the 'requested' vs 'confirmed' status lifecycle, error behavior when a room is just taken, and that Bookd never handles guest money. This is a rich disclosure well above the annotation bar.

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 preconditions, then return values, then status semantics — a logical order. It is long, but nearly every sentence carries distinct operational information (payment, instant booking, error cases). Slightly dense, but not padded.

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 returns — and it does: booking_id, optional payment_url, and the meaning of 'requested' vs 'confirmed'. Combined with error-case and idempotency guidance, an agent has everything needed to invoke and interpret the call correctly.

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 60%, so the schema already documents room, message, creator_code, slug, and date formats. The description reinforces required inputs (room, dates, guests, name, email) but adds no syntax or format detail for the undocumented parameters (guest_phone, check-out semantics) beyond what the schema provides, so it lands at the baseline 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 (send a booking request) and resource (a stay at a property for a room/unit and dates), and distinguishes itself from siblings by naming booking_status for follow-up and check_availability implicitly via the room parameter. An agent can tell it apart from cancel_booking or search_stays without opening schemas.

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?

Explicit precondition: 'Only call after the guest has confirmed the room, dates, guests, and given their name and email.' It also gives an explicit do-not: 'do not retry after a booking_id is returned (use booking_status),' naming the alternative tool. When-to-use and when-not-to-use are both covered.

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?

Goes well past the read-only/idempotent annotations: discloses availability filtering (only properties free every night), result ordering (cheapest first, exact town matches first), pagination, all returned fields including deposit handling rules, the partner_results fallback and its commercial/terms implications, and a privacy note that only location text is sent to Trip.com.

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?

A single dense paragraph with the core purpose front-loaded and the partner fallback placed after the primary behavior. It is long, but nearly every clause carries operational information; the partner-hotels section could be tightened slightly.

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 15 parameters and no output schema, the description still tells the agent what each result contains (nightly price, total_price, cancellation policy, room counts, deposits) and what the fallback shape looks like. Nothing essential to calling or interpreting the call 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?

Schema coverage is 73%, so most parameters are already documented in the schema. The description reinforces overall filter behavior (price, availability, whole homes, property types) but adds little per-parameter meaning beyond what the schema strings already say, and says nothing about page, limit, guests or min_beds.

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?

Opens with a specific verb and resource ('Find independent stays bookable direct on Bookd'), enumerates the property categories covered, and scopes it to location plus dates. An agent can distinguish this from check_availability or get_property without inspecting 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?

States the read-only nature ('nothing is booked or held') and explicitly forbids using request_booking for partner results, which is a concrete when-not rule. It does not, however, say when to prefer check_availability, get_property or request_booking for actual Bookd properties, so routing to the other siblings is left implicit.

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