beds24

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

Annotations only supply destructiveHint=true; the description adds materially beyond that: inventory is blocked immediately, changes sync to connected channels, auth requires bookings write access, and it identifies the undo path. This is exactly the operational context an agent needs before performing a channel-affecting write.

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?

Four dense sentences, zero filler, with the core action front-loaded and side effects, options, undo path, and auth requirement following in priority order. Every sentence carries distinct information.

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?

Covers the side effects, key flags, auth, and recovery path for a destructive 34-parameter mutation, which is strong. The one gap is that with no output schema the description never says what a successful call returns (e.g., a booking id), which the agent would need for follow-up calls.

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 62%, so description and schema split the load. The description clarifies three booleans (checkAvailability, notifyGuest, notifyHost), but says nothing about the remaining 31 parameters, including the required roomId/arrival/departure and the status enum that controls cancellation. Adequate but with a real 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?

States a specific verb and resource ('Create a new booking in a room') plus the required inputs (dates, guest details). The mutation scope ('immediately blocks inventory and is synced to connected channels') further distinguishes it from read-only siblings like beds24_list_bookings and beds24_get_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?

Names a concrete alternative for the inverse operation ('Undo by setting status cancelled with beds24_update_booking') and states prerequisites (token with bookings write access). It also recommends a flag configuration (checkAvailability=true), though it offers no explicit guidance on when to prefer creating vs. an inquiry or request status.

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=true, so safety is covered. The description adds real behavioral context beyond that: the exact payload contents (invoice items, info items, additional guests) and that cancelled bookings are still retrievable, which the agent can't infer from the schema or annotations.

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 short sentences, front-loaded with the core action, followed by payload scope, status applicability, and an endpoint reference. Every sentence carries information and 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?

With no output schema, the description compensates by enumerating the returned components, and with only one fully documented parameter there are no gaps an agent needs filled before calling. Nothing essential is missing for a single-record read.

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 the single bookingId parameter is fully documented in the schema, so the description's 'by id' adds no syntax or format information. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Fetch one booking by id') and immediately scopes the payload to a single record with its invoice items, info items and additional guests. This distinguishes it from list-style siblings like beds24_list_bookings and beds24_get_unit_bookings, which return collections.

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?

'Works for any status, including cancelled' gives a useful usage nuance, and 'by id' implies the caller already has an identifier. However, no alternative tools are named (e.g., when to prefer beds24_list_bookings or beds24_update_booking), so the when-to-use guidance remains implied rather than explicit.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful domain context by defining endDate as the last night rather than check-out, but it says nothing about pagination behavior even though a page parameter exists, nor about rate limits or result size limits.

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 compact sentences, front-loaded with the semantic payload (per-date boolean, endDate meaning) and ending with the source endpoint. 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?

For a five-parameter, no-required, read-only list tool with full schema coverage and no output schema, the description is almost complete. The only gap is that pagination behavior and the shape of the returned availability map are left entirely to the schema and API docs.

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 every parameter is already documented in the schema, including the endDate 'last night' clarification, which the description largely repeats. Baseline 3 is warranted since the description adds no syntax or semantics beyond the 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?

The description states a specific verb and resource — per-date true/false availability for rooms over a range of nights — and pins down the return semantics (per-date boolean). It does not, however, distinguish itself from close siblings like beds24_get_room_calendar or beds24_get_room_offers, which an agent may confuse with this one.

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 guidance on when to use this tool versus the related calendar/offers tools, and no stated preconditions beyond the implicit date-range arguments. The agent must infer the selection criteria from the sibling names alone.

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 only declare readOnlyHint=true, and the description adds genuinely useful behavior: the default field set requested when no include flags are given (numAvail, minStay, maxStay, override, prices). This goes beyond the safety profile, though it omits pagination behavior and return shape.

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 resource and returned fields, then the flag behavior, then the API endpoint. No filler or redundancy.

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 13-parameter, paginated read at 46% schema coverage with no output schema, the description covers the include-flag mechanics but leaves gaps around pagination, date-range semantics, and how roomIds/propertyIds combine. Adequate but not 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 only 46% and most include flags (includePrices, includeMinStay, etc.) have no schema description, but the description compensates by explaining what those flags collectively control and the default set. It still adds nothing for page, roomIds, propertyIds, or start/endDate semantics beyond what the schema already states.

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 resource (per-day room calendar values) and enumerates the returned field groups (units available, min/max stay, multiplier, override, price1..price16). An agent can distinguish it from availability/offers tools by the calendar-value framing, though it never names a sibling 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?

Provides guidance on how to select returned fields via include flags and what happens when none are set, which is actionable. However, it gives no when-to-use vs alternatives (e.g., get_room_availability, get_room_offers) and no exclusions, so usage is only implied.

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?

readOnlyHint=true already tells the agent this is a non-mutating read, so the description's main addition is that the result carries prices and unit counts. It does not disclose pagination behavior even though the schema's page parameter references pages.nextPageExists, nor any auth/rate-limit context. Useful but shallow beyond the annotation.

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 with the core value (bookable offers with price and units) front-loaded, plus a short API path. Tight overall, though the bare endpoint reference adds little for an agent that already has the tool name.

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 10-parameter read tool with no output schema, the description covers the required-parameter intent (dates, guests) and the return shape at a high level, which is the minimum an agent needs. It leaves pagination handling and the undocumented agentCode/numChildren parameters unaddressed, 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 description coverage is 80%, so the schema already documents arrival, departure, roomIds, offerIds, propertyIds, includeTexts and page. The description only gesture-references "given dates and guests" and adds no format, constraint, or filtering detail beyond the schema, so the 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 (quote) and resource (room offers) and further specifies the payload: total price and units available per room for given dates and guests. This separates it reasonably from the bare availability sibling, though it never names beds24_get_room_availability directly, so the differentiation is inferential rather than explicit.

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 before creating a booking" gives a concrete workflow position, which is clear context for when to invoke it. It stops short of naming an alternative or an exclusion (e.g. when to prefer get_room_availability for a simple calendar check), so it lands at clear-context-without-exclusions.

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=true, so the description doesn't need to argue safety, and instead it adds a genuinely useful behavioral quirk: 'Beds24 answers HTTP 200 with validToken=false for a bad token.' That warns the agent not to treat a 200 as success. It stops short of documenting caching, rate limits, or the exact response shape, so 4 rather than 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?

Three sentences, each carrying distinct information: what is checked, why to call it, and the HTTP 200 pitfall. The purpose is front-loaded and the endpoint reference is a compact trailing detail.

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 parameters, no output schema, and annotations covering the safety profile, the description supplies the remaining needed context by listing the returned fields (scopes, owner id, expiry, restriction) and the misleading-status caveat. An agent has everything required to call and interpret it.

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 the baseline of 4 applies; there is no argument surface the description could or should explain.

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 ('Check the configured Beds24 token') and enumerates exactly what is reported: validity, scopes, owner id, expiry, and property restriction. This is clearly distinguishable from every sibling, which all deal with bookings, rooms, or messages rather than auth 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?

'A cheap way to confirm setup and see which scopes are granted' gives a clear use context for diagnosis/setup verification. It does not name a when-not or an alternative, but no sibling overlaps this capability, so the gap is minor.

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?

readOnlyHint=true already establishes the safety profile, so the description's main added value is the disclosure that 'Beds24 marks this endpoint Beta' and the mapping to GET /inventory/rooms/unitBookings, which are genuine traits not present in the annotations. It does not cover any other behavioral aspect such as pagination behavior or result size limits, so it earns credit but not a top score.

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?

The core purpose is front-loaded in the first clause and the whole definition is short, with no filler sentences. The trailing 'Beds24: GET /inventory/rooms/unitBookings' line is arguably redundant bookkeeping but cheap and not disruptive.

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 read-only grid query with full schema coverage and no output schema, the description covers the essentials and even sketches the return shape ('occupancy grid keyed by date'). However, with zero required parameters and both roomIds and propertyIds optional, the description never indicates whether either is needed or how they interact — a gap that matters for correct invocation.

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 schema already documents page, startDate, endDate, roomIds and propertyIds including their formats. The description's 'endDate is the last night' restates what the schema already says ('Last night, YYYY-MM-DD'), adding no new semantics. Baseline 3 is appropriate when the schema does all the heavy lifting.

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 specific verb and resource: 'Which units of each room type are booked on each date — an occupancy grid keyed by date.' That is much sharper than a title restatement and tells the agent this is a unit-level occupancy snapshot. It does not, however, explicitly distinguish itself from close siblings like get_room_availability or get_room_calendar.

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 when-to-use guidance and no exclusions. The only operational remark is 'endDate is the last night,' which is a date-interpretation note rather than a routing rule, and nothing tells the agent why it would pick this over the availability or calendar endpoints in the sibling list.

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 readOnlyHint=true already covering the safety profile, the description adds genuinely useful context beyond annotations: a hard result cap ('At most 100 per call') and a stability warning ('Beds24 marks this endpoint Beta'). It stops short of describing pagination beyond the cap or any auth/prerequisite behavior.

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 what is returned, then the limit, then the beta notice and underlying endpoint. Every clause carries information an agent can act on; nothing is redundant.

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 simple read-only, single-parameter list tool the description is close to complete: it covers return fields, the 100-item cap, and a beta caveat, while readOnlyHint covers safety. Missing only minor details such as ordering or behavior past the cap.

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 the single parameter (roomId) is fully documented in the schema, so the baseline is 3. The description's 'for one room' corroborates the parameter but adds no syntax, format, or edge-case meaning beyond 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 and resource ('Guest reviews from Airbnb') and enumerates the returned fields (overall/category ratings, public review, private feedback, host response). The Airbnb scope makes it distinguishable from the sibling beds24_list_booking_com_reviews 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?

There is no when-to-use guidance, no exclusions, and no reference to the alternate review source (beds24_list_booking_com_reviews). The 'for one room' phrase hints at scope but does not tell an agent when this tool is the right choice versus its sibling.

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=true, but the description adds real behavioral context beyond them: a hard cap of 100 results per call, the Alpha stability warning, and the underlying endpoint. It does not cover error behavior or whether the 100 cap implies truncation with no pagination, leaving a small gap.

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, front-loaded with what is returned, followed by cap, stability, and endpoint metadata. Every clause carries information.

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 returned fields (scores, content, reviewer, reply) and discloses the result cap and Alpha status. For a simple two-parameter read tool, nothing an agent needs to call it correctly 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 description coverage is 100%, so both parameters are fully documented in the schema. The description restates the date filter and property scoping but adds no format, default, or edge-case detail beyond it, so the baseline of 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 (list) and resource (Booking.com guest reviews) scoped to one property and a date filter. The source platform distinguishes it from the sibling beds24_list_airbnb_reviews 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?

Usage is implied by the 'one property' and 'on or after a date' scoping, but there is no explicit when-to-use or when-not-to-use guidance, and no routing language referencing the Airbnb review sibling as an alternative.

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 readOnlyHint=true already covering the safety profile, the description adds real value: a required scope for authorization, an upstream maturity warning ('Beds24 marks this endpoint Alpha'), and the backing REST endpoint GET /bookings/invoices. It does not mention pagination behavior, though the schema covers that.

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 short sentences, each carrying a distinct fact (what is returned, the auth scope, the stability signal and upstream route). Purpose is front-loaded 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?

For a two-parameter, read-only list tool with no output schema, the description covers what is returned (invoices plus line items) and the auth requirement, which is the essential missing structured context. Pagination and filtering semantics live in the schema, so nothing essential is absent, though a note on result volume or pagination expectations would round it out.

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 bookingIds and page are already documented with usage hints (the page description even points at pages.nextPageExists). The description adds no parameter-level detail beyond the schema, so the 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 and resource ('List invoices and their line items') with the scope narrowed to bookings, and even names the payload contents (charges and payments). It clearly separates the invoices resource from the sibling bookings-list tools, but it never explicitly differentiates itself from any named sibling.

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 only guidance is a prerequisite, 'Requires the bookings-financial scope,' which is useful but is an auth requirement rather than a when-to-use statement. There is no statement of when this is preferable to beds24_list_bookings or beds24_get_booking, so usage is only implied by the resource name.

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?

readOnlyHint=true already establishes this is a safe read, and the description usefully adds the cross-channel scope and the content-type breakdown. It does not mention pagination behavior, return shaping, or rate limits, but for a read-only list tool with annotations carrying the safety profile, this is reasonable.

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 core action, then scoped via a compact em-dash clause and a filter clause, closing with the underlying endpoint. No wasted sentences for the amount of information conveyed.

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 9-parameter filter tool with no output schema, the description covers what the messages contain and the filtering surface, which is enough for correct invocation. It stops short of explaining response shape or pagination details, though the page parameter's schema note partly compensates.

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 89%, so the schema already documents the parameters well, establishing a baseline of 3. The description names filter dimensions that map onto parameters but adds no format or syntax detail beyond what the schema provides.

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/list) and resource (booking messages), then enumerates the exact content types returned (guest messages, host replies, internal notes, system messages) and the channels covered. This clearly separates it from siblings like beds24_send_booking_message and beds24_mark_messages_read without needing to open their 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?

The filter enumeration (booking, property, room, read/unread, source, age) implicitly signals the retrieval use cases, but there is no explicit when-to-use statement nor any routing to alternatives such as mark_messages_read or send_booking_message. Adequate but leaves the agent to infer selection.

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 only declare readOnlyHint=true, but the description adds substantive behavior: the no-filter default of returning only upcoming bookings, the required bookings-personal / bookings-financial scopes for guest and invoice data, and the filter semantics. It does not discuss pagination (left to the schema) or result size, so it is strong rather than exhaustive.

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?

Dense but front-loaded: the filterable dimensions come first, then the no-filter default, then the shortcut meanings, then scopes. Every sentence carries information, though the middle sentence packs four unrelated facts together and could be split for readability.

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 24-parameter, zero-required read tool with no output schema, the description supplies the essential missing context: default result scope, filter shortcuts, and permission scopes. Pagination behavior is delegated to the schema and no return shape is given, but that is acceptable given the schema's page parameter documents nextPageExists.

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 83%, so the baseline is 3; the description goes beyond it by decoding the otherwise undocumented `filter` enum values (arrivals/departures/new/current), clarifying what searchString matches, and tying includeGuests/includeInvoiceItems to their required scopes. The date-range parameter pairs are left to 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?

States a precise verb (Search) and resource (bookings) plus the full set of filterable dimensions, so the agent immediately knows this is the listing/search endpoint rather than a create/get/update sibling. It also maps to the underlying API operation (GET /bookings), anchoring intent.

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 when-to-use context via the filter shortcuts (arrivals/departures/new/current) and explains the default behavior with no filters (upcoming bookings only), which is exactly the guidance needed to pick a call shape. It stops short of naming sibling alternatives such as get_booking for single-record fetches.

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=true, so the safety profile is covered and the bar for the description is lower. The field enumeration adds useful context about what data the rule objects expose, but nothing about permissions, pagination behaviour (beyond the schema's page note), or result size limits is disclosed. Adequate, not rich.

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 names the resource first, then the payload contents, followed by a short endpoint reference. The mid-sentence field list is long but each item carries information; nothing is redundant 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 usefully enumerates the fields a fixed price rule returns, which is exactly the gap it needs to fill. Combined with annotation-covered safety and a mostly documented filter schema, it is nearly complete; only the undocumented includeRateCodes flag and lack of any auth/pagination note keep it from a 5.

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 80%, so the schema already documents page, roomIds, propertyIds, and fixedPriceIds — the baseline of 3 applies. The description adds no input-side meaning; notably includeRateCodes has no schema description and is not clarified here, leaving one genuinely opaque parameter unexplained.

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 the exact resource (fixed price rules / seasonal rates) and enumerates the returned content (date span, min/max nights, per-room/per-person prices, discounts, arrival days, channel export). It also anchors the operation to the underlying REST endpoint, so an agent can tell this apart from every sibling, none of which deal with fixed price rules.

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 when-to-use, when-not-to-use, or alternative-tool guidance. It is a read-only listing tool with optional filters, but the description never explains the scenario that should trigger it or how it relates to other inventory/rate tools such as the room calendar calls.

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=true, so the safety profile is covered. The description adds real behavioral context beyond annotations: the required 'properties' scope (auth need) and the optional flag set that changes the shape of the response.

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 returned fields, then flags, then scope, then the raw endpoint. Three efficient sentences with little waste, though the trailing 'Beds24: GET /properties' adds marginal value to an agent.

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-param, no-required, no-output-schema read tool, the description covers the return shape, optional flag behavior and auth scope adequately. Pagination and language/price-rule nuances remain only in the schema, a minor 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 coverage is 73% (above 50% but below 80%), so the schema documents most parameters. The description summarizes several flags (texts, pictures, offers, unit details, all rooms), adding orientation, but omits page, roomIds, propertyIds, includeLanguages, includePriceRules and includeUpsellItems, so it does not fully compensate.

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?

Clear specific verb+resource: 'List the properties in the account' and it enumerates what is returned (address, currency, check-in times, room types). The resource 'properties' naturally separates it from the booking/room siblings, 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?

Usage is implied by the tool name/resource, and it notes 'Requires the properties scope' as a prerequisite. However, it gives no when-to-use vs alternative guidance and no exclusions, so an agent must infer context.

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 carry destructiveHint=true, so the safety profile is covered by structured data. The description adds the underlying API call (POST /bookings/messages with [{id, read}]) and discloses the read/unread toggle, but says nothing about auth requirements, rate limits, or what the response contains.

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, front-loaded with the action before the API detail. Nothing is filler, though the endpoint reference is more implementation trivia than agent-facing 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?

For a 2-parameter mutation with full schema coverage and no output schema, the description covers what the tool does and its mode flag. Missing only usage routing, which is not strictly required for correct invocation.

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 both parameters (messageIds, read) are already documented including defaults and maxItems limits. The description merely restates the read=false semantics already present in the schema, adding no syntax or format 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 ('Mark ... as read') and resource ('booking messages'), and distinguishes itself implicitly from the sibling list/send message tools. It also clarifies the operation is bidirectional (read=false), which prevents an agent from assuming a one-way action.

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?

No explicit when-to-use, when-not-to-use, or alternative-tool guidance. The read=false note implies a usage condition but the description never says when to prefer this over beds24_list_booking_messages or beds24_send_booking_message.

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 only supply destructiveHint=true; the description explains the source of that destructiveness (message is delivered to the guest through Airbnb/Booking.com/Vrbo/email and cannot be unsent) plus the private-note alternative. It adds real behavioral value, though it omits auth requirements, rate limits, and what a successful send returns.

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 sentences, no filler, with the primary action first, the mode-dependent behavior second, and the endpoint reference last. Every clause carries information the caller 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?

With no output schema and only a destructiveHint annotation, the description carries the necessary burden and does so: it covers both modes, their audience, irreversibility, and the underlying API path. Nothing material is missing for correct invocation.

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 parameters are already documented, and the description largely restates the source enum semantics. It adds the channel-delivery implication of source=host, but no new syntax or constraints beyond the schema, so the 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 (send) and resource (a message on a booking's conversation), and the description's two-mode framing clearly separates this from sibling readers like beds24_list_booking_messages and beds24_mark_messages_read. An agent can tell what this tool does without opening 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?

It gives explicit conditional guidance on the two modes (default source=host delivers to the guest; source=internalNote is a private note) and the consequence that selecting host cannot be undone. It does not explicitly route the agent away from related siblings such as mark_messages_read, so it stops short of full when/when-not coverage.

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 only destructiveHint=true provided, the description adds real behavioral context: patch semantics (only passed fields mutate), that cancellation is reversible by resetting status, that addInfoItems appends without touching existing items, and that changes propagate to channels 'where allowed.' It stops short of disclosing required permissions, error behavior for invalid ids, or channel-sync failure handling.

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?

Dense, front-loaded, and nearly every clause carries information (patch semantics, info items, channel sync, endpoint mapping). The first sentence is a long enumeration that could be tightened slightly, but overall there is little waste.

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 33-parameter mutation tool with no output schema, the definition covers the essentials an agent needs: partial-update behavior, the cancellable status, side effects on channels, and the underlying API call. Minor gaps remain around error handling and override-vs-append behavior for notes/comments fields.

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 moderate (61%) across 33 parameters, and the description compensates by grouping fields into recognizable categories and clarifying status and addInfoItems semantics. It adds no format/syntax detail beyond the schema, so it stays at the baseline-plus level rather than genuinely enriching parameter meaning.

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 ('Change an existing booking') and enumerates the mutable domain (dates, room/unit, guest counts, guest details, notes, flag, price, status), which clearly separates it from beds24_create_booking and the read-only getters. An agent can identify the tool's scope without inspecting 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?

The partial-update rule ('Only the fields you pass change') gives useful invocation context, and the status example implicitly signals cancellation usage. However, it never states when to prefer this over sibling tools (create_booking, get_booking) or any preconditions such as a valid existing bookingId.

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 only flag destructiveHint=true. The description adds behavior the annotations cannot convey: values sync to external channels, a date range is overwritten per-day, and null explicitly removes a price. The restore-oriented warning signals the mutation is not trivially reversible.

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 scoping constraint, then fields, then the destructive warning and endpoint. The enumeration of override values and price1..price16 is slightly dense, but each clause carries information useful to invocation.

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 24-parameter destructive mutation with no output schema, the description covers impact (channel sync), reversibility (read-first/restore), and null semantics. It does not state whether omitted fields are left untouched, which is the main 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 83%, so the baseline is 3. The description names fields and the override values, but these are already present in the schema (including the 'null removes it' semantics on each price slot), so it adds little beyond what structured data provides.

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 (Set) plus resource (per-day calendar values) and scope (ONE room over a date range), then enumerates the affected fields. It is immediately distinguishable from beds24_get_room_calendar and the booking siblings without opening a 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?

Explicitly names the alternative and the prerequisite workflow: 'Read the current values first with beds24_get_room_calendar so you can restore them.' This gives the agent both when-to-use and a safety precondition, which is more than most definitions offer.

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